Developer CD Series 1994 August: Tool Chest

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1994 August: Tool Chest / Dev.CD Aug 94.toast / Tool Chest / Development Platforms / Macintosh Common Lisp Related / interfaces / PInterface Translator / PInterfacesHelp < prev next >

Wrap

Text File | 1993-09-16 | 2.0 MB | 56,725 lines | [TEXT/MPS ]

Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents. æKY CopyrightNotice æC Copyright Apple Computer, Inc. 1985-1990, All rights reserved. 411 - PInterfaces Help - MPW 3.2 Alpha Release. Friday, January 12, 1990 3:27:56 PM æKY Help,PInterfacesHelp æKL AppleTalk.p Controls.p CursorCtl.p Desk.p DeskBus.p Devices.p Dialogs.p DisAsmLookup.p DiskInit.p Disks.p ErrMgr.p Errors.p Events.p Files.p FixMath.p Fonts.p Globals Graf3D.p HyperXCmd.p Lists.p Memory.p Menus.p Notification.p OSEvents.p OSUtils.p Packages.p Palettes.p Perf.p Picker.p Printing.p Quickdraw.p Resources.p Retrace.p ROMDefs.p SANE.p Scrap.p Script.p SCSI.p SCSIIntf.p SegLoad.p Serial.p ShutDown.p Signal.p Slots.p Sound.p Start.p Strings.p SysEqu.p TextEdit.p Timer.p ToolUtils.p Types.p Video.p Windows.p æKY AppleTalk.p æKL AFPCommand ASPAbortOS ASPCloseAll ASPCloseSession ASPGetParms ASPGetStatus ASPOpenSession ASPUserCommand ASPUserWrite ATPAddRsp ATPCloseSocket ATPGetRequest ATPLoad ATPOpenSocket ATPReqCancel ATPRequest ATPResponse ATPRspCancel ATPSndRequest ATPSndRsp ATPUnload BuildBDS BuildDDPwds BuildLAPwds DDPCloseSocket DDPOpenSocket DDPRdCancel DDPRead DDPWrite GetBridgeAddress GetNodeAddress IsATPOpen IsMPPOpen LAPCloseProtocol LAPOpenProtocol LAPRdCancel LAPRead LAPWrite MPPClose MPPOpen NBPConfirm NBPExtract NBPLoad NBPLookup NBPRegister NBPRemove NBPSetEntity NBPSetNTE NBPUnload OpenXPP PAddResponse PAttachPH PCloseATPSkt PCloseSkt PConfirmName PDetachPH PGetRequest PKillGetReq PKillNBP PKillSendReq PLookupName PNSendRequest POpenATPSkt POpenSkt PRegisterName PRelRspCB PRelTCB PRemoveName PSendRequest PSendResponse PSetSelfSend PWriteDDP PWriteLAP RemoveHdlBlocks ABByte ABCallType ABProtoType ABRecHandle ABRecPtr ABusRecord AddrBlock afpAddAPPL afpAddCmt afpAddIcon afpByteRangeLock AFPCommandBlock afpContLogin afpCopyFile afpDelete afpDirClose afpDirCreate afpDTClose afpDTOpen afpEnumerate afpFileCreate afpFlush afpForkClose afpForkFlush afpGetAPPL afpGetCmt afpGetDirParms afpGetFileParms afpGetFlDrParms afpGetForkParms afpGetIcon afpGetSInfo afpGetSParms afpGetVolParms afpGtIcnInfo afpLogin afpLogout afpMapID afpMapName afpMove afpOpenDir afpOpenFork afpOpenVol afpRead afpRename afpRmvAPPL afpRmvCmt afpSetDirParms afpSetFileParms afpSetFlDrParms afpSetForkParms afpSetVolParms afpVolClose afpWrite ATPaddrBlock ATPAddRsp ATPAddRsp ATPaKillQEl ATPatpFlags ATPatpSocket ATPbdsPointer ATPbdsSize ATPbitMap ATPcsCode atpEOMvalue ATPioCompletion ATPioRefNum ATPioResult ATPnumOfBuffs ATPnumOfResps ATPParamBlock ATPPBPtr atpProto ATPreqLength ATPreqPointer ATPreqTID ATPretryCount ATPrspNum atpSendChkvalue atpSize atpSTSvalue atpTIDValidvalue ATPtimeOutVal ATPtransID ATPuserData atpXOvalue BDSElement BDSPtr BDSType BitMapType DDPchecksumFlag DDPlistener ddpProto ddpSize DDPsocket DDPwdsPointer DDPWrite DDPWrite EntityName EntityPtr LAPAdrBlock LAPhandler lapProto LAPprotType lapSize LAPwdsPointer MPPcsCode MPPioCompletion MPPioRefNum MPPioResult MPPParamBlock MPPParmType MPPPBPtr NamesTableEntry NBPconfirmAddr NBPcount NBPentityPtr NBPinterval NBPmaxToGet NBPnewSocket NBPnKillQEl NBPntQElPtr NBPnumGotten nbpProto NBPretBuffPtr NBPretBuffSize nbpSize NBPverifyFlag OpenXPP OpenXPP RetransType scbMemSize Str32 tATPAddRsp tATPGetRequest tATPRequest tATPResponse tATPSdRsp tATPSndRequest tDDPRead tDDPWrite tLAPRead tLAPWrite tNBPConfirm tNBPLookup tNBPRegister WDSElement XPPEndPrmType xppFlagClr xppFlagSet xppLoadedBit XPPParamBlock XPPParmBlkPtr XPPPrmBlkType xppRefNum XPPSubPrmType xppUnitNum æKY XPPEndPrmType æFp AppleTalk.p æT TYPE æC XPPEndPrmType = (AFPLoginPrm,ASPEndPrm); æKY XPPParmBlkPtr,XPPParamBlock æFp AppleTalk.p æT TYPE æC XPPParmBlkPtr = ^XPPParamBlock; XPPParamBlock = PACKED RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} ioTrap: INTEGER; {routine trap} ioCmdAddr: Ptr; {routine address} ioCompletion: ProcPtr; {completion routine} ioResult: OSErr; {result code} cmdResult: LONGINT; {command result(ATP user bytes)} ioVRefNum: INTEGER; {volume reference or drive number} ioRefNum: INTEGER; {driver reference number} csCode: INTEGER; {call command code} CASE XPPPrmBlkType OF ASPAbortPrm: (abortSCBPtr: Ptr); {SCB pointer for AbortOS} ASPSizeBlk: (aspMaxCmdSize: INTEGER; {for SPGetParms} aspQuantumSize: INTEGER; {for SPGetParms} numSesss: INTEGER); {for SPGetParms} XPPPrmBlk: (sessRefnum: INTEGER; {offset to session refnum} aspTimeout: Byte; {timeout for ATP} aspRetry: Byte; {retry count for ATP} CASE XPPSubPrmType OF ASPOpenPrm: (serverAddr: AddrBlock; {server address block} scbPointer: Ptr; {SCB pointer} attnRoutine: Ptr); {attention routine pointer} ASPSubPrm: (cbSize: INTEGER; {command block size} cbPtr: Ptr; {command block pointer} rbSize: INTEGER; {reply buffer size} rbPtr: Ptr; {reply buffer pointer} CASE XPPEndPrmType OF AFPLoginPrm: (afpAddrBlock: AddrBlock; {address block in AFP login} afpSCBPtr: Ptr; {SCB pointer in AFP login} afpAttnRoutine: Ptr); {Attn routine pointer in AFP login} ASPEndPrm: (wdSize: INTEGER; {write data size} wdPtr: Ptr; {write data pointer} ccbStart: ARRAY [0..295] OF Byte))); {afpWrite max size = 296, else 150} END; æKY ATPPBPtr,ATPParamBlock æFp AppleTalk.p æT TYPE æC ATPPBPtr = ^ATPParamBlock; ATPParamBlock = PACKED RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} ioTrap: INTEGER; {routine trap} ioCmdAddr: Ptr; {routine address} ioCompletion: ProcPtr; {completion routine} ioResult: OSErr; {result code} userData: LONGINT; {ATP user bytes} reqTID: INTEGER; {request transaction ID} ioRefNum: INTEGER; {driver reference number} csCode: INTEGER; {Call command code automatically set} atpSocket: Byte; {currBitMap or socket number} atpFlags: Byte; {control information} addrBlock: AddrBlock; {source/dest. socket address} reqLength: INTEGER; {request/response length} reqPointer: Ptr; {-> request/response data} bdsPointer: Ptr; {-> response BDS} CASE MPPParmType OF SendRequestParm: (numOfBuffs: Byte; {number of responses expected} timeOutVal: Byte; {timeout interval} numOfResps: Byte; {number of responses actually received} retryCount: Byte; {number of retries} intBuff: INTEGER); {used internally for NSendRequest} SendResponseParm: (filler0: Byte; {numOfBuffs} bdsSize: Byte; {number of BDS elements} transID: INTEGER); {transaction ID} GetRequestParm: (bitMap: Byte; {bit map} filler1: Byte); AddResponseParm: (rspNum: Byte; {sequence number} filler2: Byte); KillSendReqParm: (aKillQEl: Ptr); {ptr to Q element to cancel} END; æKY XPPPrmBlkType æFp AppleTalk.p æT TYPE æC XPPPrmBlkType = (XPPPrmBlk,ASPSizeBlk,ASPAbortPrm); æKY XPPSubPrmType æFp AppleTalk.p æT TYPE æC XPPSubPrmType = (ASPOpenPrm,ASPSubPrm); æKY MPPParmType æFp AppleTalk.p æT TYPE æC MPPParmType = (LAPWriteParm,AttachPHParm,DetachPHParm,OpenSktParm,CloseSktParm, WriteDDPParm,OpenATPSktParm,CloseATPSktParm,SendRequestParm,GetRequestParm, SendResponseParm,AddResponseParm,RelTCBParm,RelRspCBParm,RegisterNameParm, LookupNameParm,ConfirmNameParm,RemoveNameParm,SetSelfSendParm,NSendRequestParm, KillSendReqParm,KillGetReqParm,KillNBPParm); æKY MPPParamBlock,MPPPBPtr æFp AppleTalk.p æT TYPE æC MPPPBPtr = ^MPPParamBlock; MPPParamBlock = PACKED RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} ioTrap: INTEGER; {routine trap} ioCmdAddr: Ptr; {routine address} ioCompletion: ProcPtr; {completion routine} ioResult: OSErr; {result code} ioNamePtr: StringPtr; {->filename} ioVRefNum: INTEGER; {volume reference or drive number} ioRefNum: INTEGER; {driver reference number} csCode: INTEGER; {call command code AUTOMATICALLY set} CASE MPPParmType OF LAPWriteParm: (filler0: INTEGER; wdsPointer: Ptr); {->Write Data Structure} AttachPHParm,DetachPHParm: (protType: Byte; {ALAP Protocol Type} filler1: Byte; handler: Ptr); {->protocol handler routine} OpenSktParm,CloseSktParm,WriteDDPParm: (socket: Byte; {socket number} checksumFlag: Byte; {checksum flag} listener: Ptr); {->socket listener routine} RegisterNameParm,LookupNameParm,ConfirmNameParm,RemoveNameParm: (interval: Byte; {retry interval} count: Byte; {retry count} entityPtr: Ptr; {->names table element or ->entity name} CASE MPPParmType OF RegisterNameParm: (verifyFlag: Byte; {set if verify needed} filler3: Byte); LookupNameParm: (retBuffPtr: Ptr; {->return buffer} retBuffSize: INTEGER; {return buffer size} maxToGet: INTEGER; {matches to get} numGotten: INTEGER); {matched gotten} ConfirmNameParm: (confirmAddr: AddrBlock; {->entity} newSocket: Byte; {socket number} filler4: Byte)); SetSelfSendParm: (newSelfFlag: Byte; {self-send toggle flag} oldSelfFlag: Byte); {previous self-send state} KillNBPParm: (nKillQEl: Ptr); {ptr to Q element to cancel} END; æKY ABusRecord,ABRecPtr,ABRecHandle æFp AppleTalk.p æT TYPE æC ABRecPtr = ^ABusRecord; ABRecHandle = ^ABRecPtr; ABusRecord = RECORD abOpcode: ABCallType; abResult: INTEGER; abUserReference: LONGINT; CASE ABProtoType OF lapProto: (lapAddress: LAPAdrBlock; lapReqCount: INTEGER; lapActCount: INTEGER; lapDataPtr: Ptr); ddpProto: (ddpType: Byte; ddpSocket: Byte; ddpAddress: AddrBlock; ddpReqCount: INTEGER; ddpActCount: INTEGER; ddpDataPtr: Ptr; ddpNodeID: Byte); nbpProto: (nbpEntityPtr: EntityPtr; nbpBufPtr: Ptr; nbpBufSize: INTEGER; nbpDataField: INTEGER; nbpAddress: AddrBlock; nbpRetransmitInfo: RetransType); atpProto: (atpSocket: Byte; atpAddress: AddrBlock; atpReqCount: INTEGER; atpDataPtr: Ptr; atpRspBDSPtr: BDSPtr; atpBitmap: BitMapType; atpTransID: INTEGER; atpActCount: INTEGER; atpUserData: LONGINT; atpXO: BOOLEAN; atpEOM: BOOLEAN; atpTimeOut: Byte; atpRetries: Byte; atpNumBufs: Byte; atpNumRsp: Byte; atpBDSSize: Byte; atpRspUData: LONGINT; atpRspBuf: Ptr; atpRspSize: INTEGER); END; _______________________________________________________________________________ »CALLING THE APPLETALK MANAGER FROM PASCAL _______________________________________________________________________________ This section discusses how to use the AppleTalk Manager from Pascal. Equivalent assembly-language information is given in the “Calling the AppleTalk Manager from Assembly Language” section. You can execute many AppleTalk Manager routines either synchronously (meaning that the application can’t continue until the routine is completed) or asynchronously (meaning that the application is free to perform other tasks while the routine is being executed). When an application calls an AppleTalk Manager routine asynchronously, an I/O request is placed in the appropriate driver’s I/O queue, and control returns to the calling program—possibly even before the actual I/O is completed. Requests are taken from the queue one at a time, and processed; meanwhile, the calling program is free to work on other things. The routines that can be executed asynchronously contain a Boolean parameter called async. If async is TRUE, the call is executed asynchronously; otherwise the call is executed synchronously. Every time an asynchronous routine call is completed, the AppleTalk Manager posts a network event. The message field of the event record will contain a handle to the parameter block that was used to make that call. Most AppleTalk Manager routines return an integer result code of type OSErr. Each routine description lists all of the applicable result codes generated by the AppleTalk Manager, along with a short description of what the result code means. Lengthier explanations of all the result codes can be found in the summary at the end of the chapter. Result codes from other parts of the Operating System may also be returned. (See Appendix A for a list of all result codes.) Many Pascal calls to the AppleTalk Manager require information passed in a parameter block of type ABusRecord. The exact content of an ABusRecord depends on the protocol being called: TYPE ABProtoType = (lapProto,ddpProto,nbpProto,atpProto); ABusRecord = RECORD abOpcode: ABCallType; {type of call} abResult: INTEGER; {result code} abUserReference: LONGINT; {for your use} CASE ABProtoType OF lapProto: . . . {ALAP parameters} ddpProto: . . . {DDP parameters} nbpProto: . . . {NBP parameters} atpProto: . . . {ATP parameters} END; END; ABRecPtr = ^ABusRecord; ABRecHandle = ^ABRecPtr; The value of the abOpcode field is inserted by the AppleTalk Manager when the call is made, and is always a member of the following set: TYPE ABCallType = (tLAPRead,tLAPWrite,tDDPRead,tDDPWrite,tNBPLookup, tNBPConfirm,tNBPRegister,tATPSndRequest, tATPGetRequest,tATPSdRsp,tATPAddRsp,tATPRequest, tATPRespond); The abUserReference field is available for use by the calling program in any way it wants. This field isn’t used by the AppleTalk Manager routines or drivers. The size of an ABusRecord data structure in bytes is given by one of the following constants: CONST lapSize = 20; ddpSize = 26; nbpSize = 26; atpSize = 56; Variables of type ABusRecord must be allocated in the heap with Memory Manager NewHandle calls. For example: myABRecord := ABRecHandle(NewHandle(ddpSize)) Warning: These Memory Manager calls can’t be made inside interrupts. Routines that are executed asynchronously return control to the calling program with the result code noErr as soon as the call is placed in the driver’s I/O queue. This isn’t an indication of successful call completion; it simply indicates that the call was successfully queued to the appropriate driver. To determine when the call is actually completed, you can either check for a network event or poll the abResult field of the call’s ABusRecord. The abResult field, set to 1 when the call is made, receives the actual result code upon completion of the call. Warning: A data structure of type ABusRecord is often used by the AppleTalk Manager during an asynchronous call, and so is locked by the AppleTalk Manager. Don’t attempt to unlock or use such a variable. Each routine description includes a list of the ABusRecord fields affected by the routine. The arrow next to each field name indicates whether it’s an input, output, or input/output parameter: Arrow Meaning --> Parameter is passed to the routine <-- Parameter is returned by the routine <-> Parameter is passed to and returned by the routine æKY ABByte æFp AppleTalk.p æT TYPE æC ABByte = 1..127; æKY ABCallType,tLAPRead,tLAPWrite,tDDPRead,tDDPWrite,tNBPLookup,tNBPConfirm,tNBPRegister,tATPSndRequest,tATPGetRequest,tATPSdRsp,tATPAddRsp,tATPRequest,tATPResponse æFp Appletalk.p æC ABCallType = (tLAPRead,tLAPWrite,tDDPRead,tDDPWrite,tNBPLookup,tNBPConfirm, tNBPRegister,tATPSndRequest,tATPGetRequest,tATPSdRsp,tATPAddRsp,tATPRequest, tATPResponse); æKY ABProtoType,lapProto,ddpProto,nbpProto,atpProto æFp Appletalk.p æC ABProtoType = (lapProto,ddpProto,nbpProto,atpProto); æKY AddrBlock æFp Appletalk.p æT PACKED RECORD æC AddrBlock = PACKED RECORD aNet: INTEGER; aNode: Byte; aSocket: Byte; END; æKY afpAddAPPL æFp Appletalk.p æC afpAddAPPL = 53; {AFPCall command codes} æKY afpAddCmt æFp Appletalk.p æC afpAddCmt = 56; {AFPCall command codes} æKY afpAddIcon æFp Appletalk.p æC afpAddIcon = 192; {Special code for ASP Write commands} æKY afpByteRangeLock æFp Appletalk.p æC afpByteRangeLock = 1; {AFPCall command codes} æKY AFPCommand æFp Appletalk.p æT FUNCTION æD FUNCTION AFPCommand(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := AFPCommand(thePBptr,async); æRI AFPCommand function V-542 æC »AFPCall Function The AFPCall function can have one of the following command formats. • General • Login • AFPWrite • AFPRead »General Command Format FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer <-> 44 wdSize word Write data size --> 46 wdPtr pointer Write data pointer --> 50 ccbStart record Start of memory for CCB The general command format for the AFPCall function passes an AFP command to the server. This format is used for all AFP calls except AFPLogin, AFPRead, and AFPWrite. Note that from Pascal this call is referred to as AFPCommand. CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call by the driver. CBSize is the size in bytes of the block of data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to start of the block of data (command block) containing the command that is to be sent to the server on the session. The first byte of the command block must contain the AFP command byte. Subsequent bytes in the command buffer contain the parameters associated with the command as defined in the AFP document. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is the size of data to be written to the server (only used if the command is one that is mapped to an ASPUserWrite). WDPtr points to the write data buffer (only used if the command is one that is mapped to an ASPUserWrite). CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number; session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated afpParmError AFP command block size is equal to zero. This error will also be returned if the command byte in the command block is equal to 0 or $FF (255) or GetSrvrStatus (15). »Login Command Format The AFP login command executes a series of AFP operations as defined in the AFP Draft Proposal. For further information, refer to the AFP document. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN): OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 afpAddrBlock long word Server address block <-> 48 afpSCBPtr pointer SCB pointer <-> 52 afpAttnRoutine pointer Attention routine pointer --> 50 ccbStart record Start of command control block CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number (returned by the AFPLogin call). ASPTimeOut is the interval in seconds between retries of the call. ASPRetry is the number of retries that will be attempted. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPtr points to the block of data (command block) containing the AFP login command that is to be sent to the server on the session. The first byte of the command block must be the AFP login command byte. Subsequent bytes in the command buffer contain the parameters associated with the command. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. AFPServerAddr is the network identifier or address of the socket on which the server is listening. AFPSCBPointer points to a locked block of data for the session control block (SCB). The SCB size is defined by scbMemSize. The SCB is a locked block, and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. AFPAttnRoutine is a pointer to a routine that is invoked if an attention from the server is received. When afpAttnRoutine is equal to zero, no attention routine will be invoked. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Note: In the parameter block, the afpSCBPointer and the afpAttnRoutine fields overlap with the start of the CCB and are modified by the call. Result codes aspSizeErr Command block size is bigger than MaxCmdSize aspBufTooSmall Reply is bigger than response buffer or buffer will be filled, data will be truncated aspNoServer Server not responding aspServerBusy Server cannot open another session aspBadVersNum Server cannot support the offered ASP version number aspNoMoreSess Driver cannot support another session. »AFPWrite Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word AFP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer --> 44 wdSize word (used internally) <-> 46 wdPtr pointer Write data pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the aspGetParms call. CBPtr points to the block of data (see command block structure below) containing the AFP write command that is to be sent to the server on the session. The first byte of the Command Block must contain the AFP write command byte. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is used internally. Note: This command does not pass the write data size in the queue element but in the command buffer. XPP will look for the size in that buffer. WDPtr is a pointer to the block of data to be written. Note that this field will be updated by XPP as it proceeds and will always point to that section of the data which XPP is currently writing. CCBStart is the start of the memory to be used by the XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement refer to the CCB Sizes section later in this chapter. Command Block Structure: The AFP write command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPtr. --> 0 cmdByte byte AFP call command byte --> 1 startEndFlag byte Start/end Flag <-> 4 rwOffset long word Offset within fork to write <-> 8 reqCount long word Requested count CmdByte is the AFP call command byte and must contain the AFP write command code. StartEndFlag is a one-bit flag (the high bit of the byte) indicating whether the rwOffset field is relative to the beginning or the end of the fork (all other bits are zero). 0 = relative to the beginning of the fork 1 = relative to the end of the fork RWOffset is the byte offset within the fork at which the write is to begin. ReqCount indicates the size of the data to be written and is returned as the actual size written. The rwOffset and reqCount fields are modified by XPP as the write proceeds and will always indicate the current value of these fields. The Pascal structure of the AFP command buffer follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; {unused by write} newLineChar: CHAR; {unused by write} END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer »AFPRead Command Format The AFPWrite and AFPRead command formats allow the calling application to make AFP-level calls that read or write a data block that is larger than a single ASP-level call is capable of reading or writing. The maximum number of bytes of data that can be read or written at the ASP level is equal to quantumSize. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always AFPCall --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command buffer size --> 34 cbPtr pointer Command buffer --> 38 rbSize word Used internally <-> 40 rbPtr pointer Reply buffer pointer (updated) --> 50 ccbStart record Start of memory for CCB CmdResult is four bytes of data returned from the server containing an indication of the result of the AFP command. SessRefnum is the session reference number returned in the AFPLogin call. ASPTimeOut is the interval in seconds between retries of the call. CBSize is the size in bytes of the block data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the GetParms call. CBPtr points to the block of data (command block) containing the AFP read command that is to be sent to the server on the session. The first byte of the command block must contain the AFP read command byte. The command block structure is shown below. RBSize is used internally. Note: This command does not pass the read size in the queue element but in the command buffer. XPP will look for the size in that buffer. RBPtr points to the reply buffer. Note that this field will be updated by XPP as it proceeds and will always point to that section of the buffer that XPP is currently reading into. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to The CCB Sizes section later in this chapter. Command Block Structure: The AFP read command passes several arguments to XPP in the command buffer itself. The byte offsets are relative to the location pointed to by cbPointer. --> 0 cmdByte byte AFP call command byte <-> 4 rwOffset long word Offset within fork to read <-> 8 reqCount long word Requested count --> 12 newLineFlag byte Newline Flag --> 13 newLineChar byte Newline Character CmdByte is the AFP call command byte and must contain the AFP read command code. RWOffset is the byte offset within the fork at which the read is to begin. ReqCount indicates the size of the read data buffer and is returned as the actual size read. The rwOffset and reqCount fields are modified by XPP as the read proceeds and will always indicate the current value of these fields. NewLineFlag is a one-bit flag (the high bit of the byte) indicating whether or not the read is to terminate at a specified character (all other bits are zero). 0 = no Newline Character is specified 1 = a Newline Character is specified NewLineChar is any character from $00 to $FF (inclusive) that, when encountered in reading the fork, causes the read operation to terminate. The Pascal structure of the AFPCommand follows: AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; {unused for read} forkRefNum: INTEGER; {used by server} rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; newLineChar: CHAR; END; Result codes aspParamErr Invalid session number aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer æKY AFPCommandBlock æFp Appletalk.p æT PACKED RECORD æC AFPCommandBlock = PACKED RECORD cmdByte: Byte; startEndFlag: Byte; forkRefNum: INTEGER; rwOffset: LONGINT; reqCount: LONGINT; newLineFlag: Byte; newLineChar: CHAR; END; æKY afpContLogin æFp Appletalk.p æC afpContLogin = 19; {AFPCall command codes} æKY afpCopyFile æFp Appletalk.p æC afpCopyFile = 5; {AFPCall command codes} æKY afpDelete æFp Appletalk.p æC afpDelete = 8; {AFPCall command codes} æKY afpDirClose æFp Appletalk.p æC afpDirClose = 3; {AFPCall command codes} æKY afpDirCreate æFp Appletalk.p æC afpDirCreate = 6; {AFPCall command codes} æKY afpDTClose æFp Appletalk.p æC afpDTClose = 49; {AFPCall command codes} æKY afpDTOpen æFp Appletalk.p æC afpDTOpen = 48; {AFPCall command codes} æKY afpEnumerate æFp Appletalk.p æC afpEnumerate = 9; {AFPCall command codes} æKY afpFileCreate æFp Appletalk.p æC afpFileCreate = 7; {AFPCall command codes} æKY afpFlush æFp Appletalk.p æC afpFlush = 10; {AFPCall command codes} æKY afpForkClose æFp Appletalk.p æC afpForkClose = 4; {AFPCall command codes} æKY afpForkFlush æFp Appletalk.p æC afpForkFlush = 11; {AFPCall command codes} æKY afpGetAPPL æFp Appletalk.p æC afpGetAPPL = 55; {AFPCall command codes} æKY afpGetCmt æFp Appletalk.p æC afpGetCmt = 58; {AFPCall command codes} æKY afpGetDirParms æFp Appletalk.p æC afpGetDirParms = 12; {AFPCall command codes} æKY afpGetFileParms æFp Appletalk.p æC afpGetFileParms = 13; {AFPCall command codes} æKY afpGetFlDrParms æFp Appletalk.p æC afpGetFlDrParms = 34; {AFPCall command codes} æKY afpGetForkParms æFp Appletalk.p æC afpGetForkParms = 14; {AFPCall command codes} æKY afpGetIcon æFp Appletalk.p æC afpGetIcon = 51; {AFPCall command codes} æKY afpGetSInfo æFp Appletalk.p æC afpGetSInfo = 15; {AFPCall command codes} æKY afpGetSParms æFp Appletalk.p æC afpGetSParms = 16; {AFPCall command codes} æKY afpGetVolParms æFp Appletalk.p æC afpGetVolParms = 17; {AFPCall command codes} æKY afpGtIcnInfo æFp Appletalk.p æC afpGtIcnInfo = 52; {AFPCall command codes} æKY afpLogin æFp Appletalk.p æC afpLogin = 18; {AFPCall command codes} æKY afpLogout æFp Appletalk.p æC afpLogout = 20; {AFPCall command codes} æKY afpMapID æFp Appletalk.p æC afpMapID = 21; {AFPCall command codes} æKY afpMapName æFp Appletalk.p æC afpMapName = 22; {AFPCall command codes} æKY afpMove æFp Appletalk.p æC afpMove = 23; {AFPCall command codes} æKY afpOpenDir æFp Appletalk.p æC afpOpenDir = 25; {AFPCall command codes} æKY afpOpenFork æFp Appletalk.p æC afpOpenFork = 26; {AFPCall command codes} æKY afpOpenVol æFp Appletalk.p æC afpOpenVol = 24; {AFPCall command codes} æKY afpRead æFp Appletalk.p æC afpRead = 27; {AFPCall command codes} æKY afpRename æFp Appletalk.p æC afpRename = 28; {AFPCall command codes} æKY afpRmvAPPL æFp Appletalk.p æC afpRmvAPPL = 54; {AFPCall command codes} æKY afpRmvCmt æFp Appletalk.p æC afpRmvCmt = 57; {AFPCall command codes} æKY afpSetDirParms æFp Appletalk.p æC afpSetDirParms = 29; {AFPCall command codes} æKY afpSetFileParms æFp Appletalk.p æC afpSetFileParms = 30; {AFPCall command codes} æKY afpSetFlDrParms æFp Appletalk.p æC afpSetFlDrParms = 35; {AFPCall command codes} æKY afpSetForkParms æFp Appletalk.p æC afpSetForkParms = 31; {AFPCall command codes} æKY afpSetVolParms æFp Appletalk.p æC afpSetVolParms = 32; {AFPCall command codes} æKY afpVolClose æFp Appletalk.p æC afpVolClose = 2; {AFPCall command codes} æKY afpWrite æFp Appletalk.p æC afpWrite = 33; {AFPCall command codes} æKY ASPAbortOS æFp Appletalk.p æT FUNCTION æD FUNCTION ASPAbortOS(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPAbortOS(thePBptr,async); æRI ASPAbortOS function V-537 æC Parameter block --> 26 csCode word Always ASPAbortOS --> 28 abortSCBPointer pointer Pointer to session control block ASPAbortOS aborts a pending (not yet completed) ASPOpenSession call. The aborted ASPOpenSession call will return a reqAborted error. AbortSCBPointer points to the original SCB used in the the pending ASPOpenSession call. Result codes cbNotFound SCB not found, no outstanding open session to be aborted. Pointer did not point to an open session SCB. æKY ASPCloseAll æFp Appletalk.p æT FUNCTION æD FUNCTION ASPCloseAll(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPCloseAll(thePBptr,async); æRI ASPCloseAll function V-538 æC Parameter block --> 26 csCode word Always ASPCloseAll ASPCloseAll closes every session that the driver has active, aborting all active requests and invoking the attention routines where provided. This call should be used carefully. ASPCloseAll can be used as a system level resource for making sure all sessions are closed prior to closing the driver. æKY ASPCloseSession æFp Appletalk.p æT FUNCTION æD FUNCTION ASPCloseSession(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPCloseSession(thePBptr,async); æRI ASPCloseSession function V-537 æC Parameter block --> 26 csCode word Always ASPCloseSession --> 28 sessRefnum word Session reference number ASPCloseSession closes the session identified by the sessRefnum returned in the ASPOpenSession call. ASPCloseSession aborts any calls that are active on the session, closes the session, and calls the attention routine, if any, with an attention code of zero (zero is invalid as a real attention code). Result codes aspParamErr Parameter error, indicates an invalid session reference number aspSessClosed Session already in process of closing æKY ASPGetParms æFp Appletalk.p æT FUNCTION æD FUNCTION ASPGetParms(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPGetParms(thePBptr,async); æRI ASPGetParms function V-538 æC Parameter block --> 26 csCode word Always ASPGetParms --> 28 aspMaxCmdSize word Maximum size of command block --> 30 aspQuantumSize word Maximum data size --> 32 numSesss word Number of sessions ASPGetParms returns three ASP parameters. This call does not require an open session. ASPMaxCmdSize is the maximum size of a command that can be sent to the server. ASPQuantumSize is the maximum size of data that can be transferred to the server in a Write request or from the server in a command reply. NumSess is the number of concurrent sessions supported by the driver. æKY ASPGetStatus æFp Appletalk.p æT FUNCTION æD FUNCTION ASPGetStatus(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPGetStatus(thePBptr,async); æRI ASPGetStatus function V-540 æC Parameter block --> 26 csCode word Always ASPGetStatus --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 serverAddr long word Server socket address <-> 38 rbSize word Reply buffer and reply size --> 40 rbPtr pointer Reply buffer pointer --> 50 ccbStart record Start of memory for CCB ASPGetStatus returns server status. This call is also used as GetServerInfo at the AFP level. This call is unique in that it transfers data over the network without having a session open. This call does not pass any data but requests that server status be returned. ASPTimeOut is the interval in seconds between retries of the call. ASPRetry is the number of retries that will be attempted. ServerAddr is the network identifier or address of the socket on which the server is listening. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspBufTooSmall Reply is bigger than response buffer, or Replysize is bigger than ReplyBuffsize aspNoServer No response from server at address used in call æKY ASPOpenSession æFp Appletalk.p æT FUNCTION æD FUNCTION ASPOpenSession(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPOpenSession(thePBptr,async); æRI ASPOpenSession function V-536 æC »AppleTalk Session Protocol Functions This section contains descriptions of the .XPP driver functions that you can call. Each function description shows the required parameter block fields, their offsets within the parameter block and a brief definition of the field. Possible result codes are also described. »Note on Result Codes An important distinction exists between the aspParamErr and aspSessClose result codes that may be returned by the .XPP driver. When the driver returns aspParamErr to a call that takes as an input a session reference number, the session reference number does not relate to a valid open session. There could be several reasons for this, such as the workstation or server end closed the session or the server end of the session died. The aspSessClosed result code indicates that even though the session reference number relates to a valid session, that particular session is in the process of closing down (although the session is not yet closed). FUNCTION ASPOpenSession (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr; Parameter block --> 26 csCode word Always ASPOpenSess --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 31 aspRetry byte Number of retries --> 32 serverAddr long word Server socket address --> 36 scbPointer pointer Pointer to session control block --> 40 attnRoutine pointer Pointer to attention routine ASPOpenSession initiates (opens) a session between the workstation and a server. The required parameter block is shown above. A brief definition of the fields follows. SessRefnum is a unique number identifying the open session between the workstation and the server. The SessRefnum is returned when the function completes successfully and is used in all calls to identify the session. ASPTimeOut is the interval in seconds between retries of the open session request. ASPRetry is the number of retries that will be attempted. ServerAddr is the network identifier or address of the socket on which the server is listening. SCBPointer points to a nonrelocatable block of data for the session control block (SCB) that the .XPP driver reserves for use in maintaining an open session. The SCB size is defined by the constant scbMemSize. The SCB is a locked block and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. This block can be reused when a CloseSess call is issued and completed for that session, or when the session is indicated as closed through return of aspParamErr as the result of a call for that session. AttnRoutine is a pointer to a routine that is invoked if an attention from the server is received, or upon session closing. If this pointer is equal to zero, no attention routine will be invoked. Result codes aspNoMoreSess Driver cannot support another session aspParamErr Server returned bad (positive) error code aspNoServers No servers at that address, or the server did not respond to the request reqAborted OpenSess was aborted by an AbortOS aspBadVersNum Server cannot support the offered version number aspServerBusy Server cannot open another session Note: The number of sessions that the driver is capable of supporting depends on the machine that the driver is running on. æKY ASPUserCommand æFp Appletalk.p æT FUNCTION æD FUNCTION ASPUserCommand(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPUserCommand(thePBptr,async); æRI ASPUserCommand function V-539 æC Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always ASPUserCommand --> 28 sessRefnum word Session number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command block size --> 34 cbPtr pointer Command block pointer <-> 38 rbSize word Reply buffer and reply size --> 40 rbPtr pointer Reply buffer pointer --> 50 ccbStart record Start of memory for CCB ASPUserCommand is used to send a command to the server on a session. SessRefnum is the session reference number returned in the ASPOpenSession call. ASPTimeOut is the interval in seconds between retries of the call. Notice that there is no aspRetry field (retries are infinite). The command will be retried at the prescribed interval until completion or the session is closed. CBSize is the size in bytes of the block of data that contains the command to be sent to the server on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. CBPointer points to the block of data containing the command that is to be sent to the server on the session. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 150 bytes. To determine the exact requirement refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number, session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer; the buffer will be filled, data will be truncated æKY ASPUserWrite æFp Appletalk.p æT FUNCTION æD FUNCTION ASPUserWrite(thePBptr: XPPParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := ASPUserWrite(thePBptr,async); æRI ASPUserWrite function V-538 æC Parameter block --> 18 cmdResult long word ASP command result --> 26 csCode word Always UserWrite --> 28 sessRefnum word Session reference number --> 30 aspTimeout byte Retry interval in seconds --> 32 cbSize word Command block size --> 34 cbPtr pointer Command block pointer <-> 38 rbSize word Reply buffer size and reply size --> 40 rbPtr pointer Reply buffer pointer <-> 44 wdSize word Write data size --> 46 wdPtr pointer Write data pointer --> 50 ccbStart record Start of memory for CCB ASPUserWrite transfers data on a session. ASPUserWrite is one of the two main calls that can be used to transfer data on an ASP session. The other call that performs a similar data transfer is ASPUserCommand described below. The ASPUserWrite command returns data in two different places. Four bytes of data are returned in the cmdResult field and a variable size reply buffer is also returned. CmdResult is four bytes of data returned by the server. SessRefnum is the session reference number returned in the ASPOpenSession call. ASPTimeOut is the interval in seconds between retries of the call. Notice that there is no aspRetry field (retries are infinite). The command will be retried at the prescribed interval until completion or the session is closed. CBSize is the size in bytes of the command data that is to be written on the session. The size of the command block must not exceed the value of aspMaxCmdSize returned by the ASPGetParms call. Note that this buffer is not the data to be written by the command but only the data of the command itself. CBPtr points to the command data. RBSize is passed and indicates the size of the reply buffer in bytes expected by the command. RBSize is also returned and indicates the size of the reply that was actually returned. RBPtr points to the reply buffer. WDSize is passed and indicates the size of the write data in bytes to be sent by the command. WDSize is also returned and indicates the size of the write data that was actually written. WDPointer points to the write data buffer. CCBStart is the start of the memory to be used by the .XPP driver for the command control block. The size of this block is equal to a maximum of 296 bytes. To determine the exact requirement, refer to the CCB Sizes section of this document. Result codes aspParamErr Invalid session number, session has been closed aspSizeErr Command block size is bigger than MaxCmdSize aspSessClosed Session is closing aspBufTooSmall Reply is bigger than response buffer; the buffer will be filled, data will be truncated æKY ATPaddrBlock æFp Appletalk.p æC ATPaddrBlock = ATP.addrBlock; æKY ATPAddRsp æFp Appletalk.p æT FUNCTION æD FUNCTION ATPAddRsp(abRecord: ABRecHandle): OSErr; æDT myVariable := ATPAddRsp(abRecord); æMM æRI ATPAddRsp function II-295 æC ABusRecord <-- abOpcode {always tATPAddRsp} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {responding socket number} --> atpAddress {destination socket address} --> atpReqCount {buffer size in bytes} --> atpDataPtr {pointer to buffer} --> atpTransID {transaction ID} --> atpUserData {user bytes} --> atpEOM {end-of-message flag} --> atpNumRsp {sequence number} ATPAddRsp sends one additional response packet to a socket that has already been sent the initial part of a response via ATPSndRsp. ATPSocket contains the socket number from which the response should be sent and atpAddress contains the internet address of the socket to which the response should be sent. ATPTransID must contain the transaction ID. ATPDataPtr and atpReqCount specify the location and size of a buffer that contains the information to send; atpNumRsp is the sequence number of the response. ATPEOM is TRUE if this response datagram is the final packet in a transaction composed of a group of packets. ATPUserData contains the user bytes to be sent in this response datagram’s ATP header. Note: No BDS is needed with ATPAddRsp because all pertinent information is passed within the record. Result codes noErr No error badATPSkt Bad responding socket badBuffNum Bad sequence number noSendResp ATPAddRsp issued before ATPSndRsp noDataArea Too many outstanding ATP calls æKY ATPaKillQEl æFp Appletalk.p æC ATPaKillQEl = KILL.aKillQEl; æKY ATPatpFlags æFp Appletalk.p æC ATPatpFlags = ATP.atpFlags; æKY ATPatpSocket æFp Appletalk.p æC ATPatpSocket = ATP.atpSocket; æKY ATPbdsPointer æFp Appletalk.p æC ATPbdsPointer = ATP.bdsPointer; æKY ATPbdsSize æFp Appletalk.p æC ATPbdsSize = OTH2.bdsSize; æKY ATPbitMap æFp Appletalk.p æC ATPbitMap = OTH1.u0.bitMap; æKY ATPCloseSocket æFp Appletalk.p æT FUNCTION æD FUNCTION ATPCloseSocket(atpSocket: Byte): OSErr; æDT myVariable := ATPCloseSocket(atpSocket); æMM æRI ATPCloseSocket function II-291 æC ATPCloseSocket closes the responding socket whose number is specified by atpSocket. It releases the data structures associated with all pending, asynchronous calls involving that socket; these pending calls are completed immediately and return the result code sktClosed. Result codes noErr No error noDataArea Too many outstanding ATP calls æKY ATPcsCode æFp Appletalk.p æC ATPcsCode = ATP.csCode; æKY atpEOMvalue æFp Appletalk.p æC atpEOMvalue = 16; {ATP End-Of-Message bit } æKY ATPGetRequest æFp Appletalk.p æT FUNCTION æD FUNCTION ATPGetRequest(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := ATPGetRequest(abRecord,async); æMM æRT 20 æRI ATPGetRequest function II-293, N20-2 æC ABusRecord <-- abOpcode {always tATPGetRequest} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {listening socket number} <-- atpAddress {source socket address} --> atpReqCount {buffer size in bytes} --> atpDataPtr {pointer to buffer} <-- atpBitMap {transaction bit map} <-- atpTransID {transaction ID} <-- atpActCount {number of bytes actually received} <-- atpUserData {user bytes} <-- atpXO {exactly-once flag} ATPGetRequest sets up the mechanism to receive a request sent by either an ATPSndRequest or an ATPRequest call. ATPSocket contains the socket number of the socket that should listen for a request; this socket must already have been opened by calling ATPOpenSocket. The address of the socket from which the request was sent is returned in atpAddress. ATPDataPtr specifies a buffer to store the incoming request; atpReqCount indicates the size of the buffer in bytes. The number of bytes actually received in the request is returned in atpActCount. ATPUserData contains the user bytes from the ATP header. The transaction bit map is returned in atpBitMap. The transaction ID is returned in atpTransID. ATPXO will be TRUE if the request is part of an exactly-once transaction. ATPGetRequest completes when a request is received. To cancel an asynchronous ATPGetRequest call, you must call ATPCloseSocket, but this cancels all pending calls involving that socket. Result codes noErr No error badATPSkt Bad responding socket sktClosed Socket closed by a cancel call æKY ATPioCompletion æFp Appletalk.p æC ATPioCompletion = ATP.ioCompletion; æKY ATPioRefNum æFp Appletalk.p æC ATPioRefNum = ATP.ioRefNum; æKY ATPioResult æFp Appletalk.p æC ATPioResult = ATP.ioResult; æKY ATPLoad æFp Appletalk.p æT FUNCTION æD FUNCTION ATPLoad: OSErr; æDT myVariable := ATPLoad; æMM æRT 20, 224 æRI ATPLoad function II-290, N20-2 æC •••Refer to Technical Note #224:••• ATPLoad first verifies that the .MPP driver is loaded and running. If it isn’t, ATPLoad verifies that port B is configured for AppleTalk and isn’t in use, and then loads MPP into the system heap. ATPLoad then loads the .ATP driver, unless it’s already in memory. On a Macintosh 128K, ATPLoad reads the .ATP driver from the system resource file into the application heap; on a Macintosh 512K or XL, ATP is read into the system heap. Note: On a Macintosh 512K or XL, ATPLoad and MPPOpen perform essentially the same function. Result codes noErr No error portInUse Port B is already in use portNotCf Port B not configured for AppleTalk æKY ATPnumOfBuffs æFp Appletalk.p æC ATPnumOfBuffs = OTH1.u0.numOfBuffs; æKY ATPnumOfResps æFp Appletalk.p æC ATPnumOfResps = SREQ.numOfResps; æKY ATPOpenSocket æFp Appletalk.p æT FUNCTION æD FUNCTION ATPOpenSocket(addrRcvd: AddrBlock;VAR atpSocket: Byte): OSErr; æDT myVariable := ATPOpenSocket(addrRcvd,atpSocket); æMM æRI ATPOpenSocket function II-290 æC ATPOpenSocket opens a socket for the purpose of receiving requests. ATPSocket contains the socket number of the socket to open; if it’s 0, a number is dynamically assigned and returned in atpSocket. AddrRcvd contains a filter of the sockets from which requests will be accepted. A 0 in the network number, node ID, or socket number field of the addrRcvd record acts as a “wild card”; for instance, a 0 in the socket number field means that requests will be accepted from all sockets in the node(s) specified by the network and node fields. Result codes noErr No error tooManySkts Socket table full noDataArea Too many outstanding ATP calls Note: If you’re only going to send requests and receive responses to these requests, you don’t need to open an ATP socket. When you make the ATPSndRequest or ATPRequest call, ATP automatically opens a dynamically assigned socket for that purpose. æKY ATPReqCancel æFp Appletalk.p æT FUNCTION æD FUNCTION ATPReqCancel(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := ATPReqCancel(abRecord,async); æMM æRI ATPReqCancel function II-293 æC Given the handle to the ABusRecord of a previously made ATPSndRequest or ATPRequest call, ATPReqCancel dequeues the ATPSndRequest or ATPRequest call, provided that the call hasn’t already completed. ATPReqCancel returns noErr if the ATPSndRequest or ATPRequest call is successfully removed from the queue. If it returns cbNotFound, check the abResult field of abRecord to verify that the ATPSndRequest or ATPRequest call has completed and determine its outcome. Result codes noErr No error cbNotFound ATP control block not found æKY ATPreqLength æFp Appletalk.p æC ATPreqLength = ATP.reqLength; æKY ATPreqPointer æFp Appletalk.p æC ATPreqPointer = ATP.reqPointer; æKY ATPreqTID æFp Appletalk.p æC ATPreqTID = ATP.reqTID; æKY ATPRequest æFp Appletalk.p æT FUNCTION æD FUNCTION ATPRequest(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := ATPRequest(abRecord,async); æMM æRI ATPRequest function II-292 æC ABusRecord <-- abOpcode {always tATPRequest} <-- abResult {result code} --> abUserReference {for your use} --> atpAddress {destination socket address} --> atpReqCount {request size in bytes} --> atpDataPtr {pointer to buffer} <-- atpActCount {number of bytes actually received} --> atpUserData {user bytes} --> atpXO {exactly-once flag} <-- atpEOM {end-of-message flag} --> atpTimeOut {retry timeout interval in seconds} --> atpRetries {maximum number of retries} <-- atpRspUData {user bytes received in transaction response} --> atpRspBuf {pointer to response message buffer} --> atpRspSize {size of response message buffer} ATPRequest is functionally analogous to ATPSndRequest. It sends a request to another socket, but doesn’t require the caller to set up and use the BDS data structure to describe the response buffers. ATPAddress indicates the socket to which the request should be sent. ATPDataPtr and atpReqCount specify the location and size of a buffer that contains the request information to be sent. ATPUserData contains the user bytes to be sent in the request’s ATP header. ATPTimeOut indicates the length of time that ATPRequest should wait for a response before retransmitting the request. ATPRetries indicates the maximum number of retries ATPRequest should attempt. To use this call, you must have an area of contiguous buffer space that’s large enough to receive all expected datagrams. The various datagrams will be assembled in this buffer and returned to you as a complete message upon completion of the transaction. The location and size of this buffer are passed in atpRspBuf and atpRspSize. Upon completion of the call, the size of the received response message is returned in atpActCount. The user bytes received in the ATP header of the first response packet are returned in atpRspUData. ATPXO should be TRUE if you want the request to be part of an exactly-once transaction. Although you don’t provide a BDS, ATPRequest in fact creates one and calls the .ATP driver (as in an ATPSndRequest call). For this reason, the abRecord fields atpRspBDSPtr and atpNumBufs are used by ATPRequest; you should not expect these fields to remain unaltered during or after the function’s execution. For ATPRequest to receive and correctly deliver the response as a single message, the responding end must, upon receiving the request (with an ATPGetRequest call), generate the complete response as a message in a single buffer and then call ATPResponse. Note: The responding end could also use ATPSndRsp and ATPAddRsp provided that each response packet (except the last one) contains exactly 578 ATP data bytes; the last packet in the response can contain less than 578 ATP data bytes. Also, if this method is used, only the ATP user bytes of the first response packet will be delivered to the requester; any information in the user bytes of the remaining response packets will not be delivered. ATPRequest completes when either the transaction is completed or the retry count is exceeded. Result codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests sktClosed Socket closed by a cancel call noDataArea Too many outstanding ATP calls æKY ATPResponse æFp Appletalk.p æT FUNCTION æD FUNCTION ATPResponse(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := ATPResponse(abRecord,async); æMM æRT 20 æRI ATPResponse function II-296, N20-2 æC ABusRecord <-- abOpcode {always tATPResponse} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {responding socket number} --> atpAddress {destination socket address} --> atpTransID {transaction ID) --> atpRspUData {user bytes sent in transaction response} --> atpRspBuf {pointer to response message buffer} --> atpRspSize {size of response message buffer} ATPResponse is functionally analogous to ATPSndRsp. It sends a response to another socket, but doesn’t require the caller to provide a BDS. ATPAddress must contain the complete network address of the socket to which the response should be sent (taken from the data provided by an ATPGetRequest call). ATPTransID must contain the transaction ID. ATPSocket indicates the socket from which the response should be sent (the socket on which the corresponding ATPGetRequest was issued). ATPRspBuf points to the buffer containing the response message; the size of this buffer must be passed in atpRspSize. The four user bytes to be sent in the ATP header of the first response packet are passed in atpRspUData. The last packet of the transaction response is sent with the EOM flag set. Although you don’t provide a BDS, ATPResponse in fact creates one and calls the .ATP driver (as in an ATPSndRsp call). For this reason, the abRecord fields atpRspBDSPtr and atpNumBufs are used by ATPResponse; you should not expect these fields to remain unaltered during or after the function’s execution. During exactly-once transactions ATPResponse won’t complete until the release packet is received or the release timer expires. Warning: The maximum permissible size of the response message is 4624 bytes. Result codes noErr No error badATPSkt Bad responding socket noRelErr No release received atpLenErr Response too big sktClosed Socket closed by a cancel call noDataArea Too many outstanding ATP calls æKY ATPretryCount æFp Appletalk.p æC ATPretryCount = SREQ.retryCount; æKY ATPRspCancel æFp Appletalk.p æT FUNCTION æD FUNCTION ATPRspCancel(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := ATPRspCancel(abRecord,async); æMM æRI ATPRspCancel function II-296 æC Given the handle to the ABusRecord of a previously made ATPSndRsp or ATPResponse call, ATPRspCancel dequeues the ATPSndRsp or ATPResponse call, provided that the call hasn’t already completed. ATPRspCancel returns noErr if the ATPSndRsp or ATPResponse call is successfully removed from the queue. If it returns cbNotFound, check the abResult field of abRecord to verify that the ATPSndRsp or ATPResponse call has completed and determine its outcome. Result codes noErr No error cbNotFound ATP control block not found »Example This example shows the requesting side of an ATP transaction that asks for a 512-byte disk block from the responding end. The block number of the file is a byte and is contained in myBuffer[0]. VAR myABRecord: ABRecHandle; myBDSPtr: BDSPtr; myBuffer: PACKED ARRAY [0..511] OF CHAR; errCode: INTEGER; async: BOOLEAN; BEGIN errCode := ATPLoad; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Prepare the BDS; allocate space for a one-element BDS} myBDSPtr := BDSPtr(NewPtr(SIZEOF(BDSElement))); WITH myBDSPtr^[0] DO BEGIN buffSize := 512; {size of our buffer used in reception} buffPtr := @myBuffer; {pointer to the buffer} END; {Prepare the ABusRecord} myBuffer[0] := CHR(1); {requesting disk block number 1} myABRecord := ABRecHandle(NewHandle(atpSize)); WITH myABRecord^^ DO BEGIN atpAddress.aNet := 0; atpAddress.aNode := 30; {we probably got this from an NBP call} atpAddress.aSocket := 15; {socket to send request to} atpReqCount := 1; {size of request data field (disk block #)} atpDataPtr := @myBuffer; {ptr to request to be sent} atpRspBDSPtr := @myBDSPtr; atpUserData := 0; {for your use} atpXO := FALSE; {at-least-once service} atpTimeOut := 5; {5-second timeout} atpRetries := 3; {3 retries; request will be sent 4 times max} atpNumBufs := 1; {we're only expecting 1 block to be returned} END; async := FALSE; {Send the request and wait for the response} errCode := ATPSndRequest(myABRecord, async); IF errCode <> noErr THEN WRITELN('An error occurred in the ATPSndRequest call') ELSE BEGIN {The disk block requested is now in myBuffer. We can verify } { that atpNumRsp contains 1, meaning one response received.} . . . END; END; END. æKY ATPrspNum æFp Appletalk.p æC ATPrspNum = OTH1.u0.rspNum; æKY atpSendChkvalue æFp Appletalk.p æC atpSendChkvalue = 1; {ATP send checksum bit } æKY ATPSndRequest æFp Appletalk.p æT FUNCTION æD FUNCTION ATPSndRequest(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := ATPSndRequest(abRecord,async); æMM æRI ATPSndRequest function II-291 æC ABusRecord <-- abOpcode {always tATPSndRequest} <-- abResult {result code} --> abUserReference {for your use} --> atpAddress {destination socket address} --> atpReqCount {request size in bytes} --> atpDataPtr {pointer to buffer} --> atpRspBDSPtr {pointer to response BDS} --> atpUserData {user bytes} --> atpXO {exactly-once flag} <-- atpEOM {end-of-message flag} --> atpTimeOut {retry timeout interval in seconds} --> atpRetries {maximum number of retries} --> atpNumBufs {number of elements in response BDS} <-- atpNumRsp {number of response packets actually received} ATPSndRequest sends a request to another socket. ATPAddress is the internet address of the socket to which the request should be sent. ATPDataPtr and atpReqCount specify the location and size of a buffer that contains the request information to be sent. ATPUserData contains the user bytes for the ATP header. ATPSndRequest requires you to allocate a response BDS. ATPRspBDSPtr is a pointer to the response BDS; atpNumBufs indicates the number of elements in the BDS (this is also the maximum number of response datagrams that will be accepted). The number of response datagrams actually received is returned in atpNumRsp; if a nonzero value is returned, you can examine the response BDS to determine which packets of the transaction were actually received. If the number returned is less than requested, one of the following is true: • Some of the packets have been lost and the retry count has been exceeded. • ATPEOM is TRUE; this means that the response consisted of fewer packets than were expected, but that all packets sent were received (the last packet came with the atpEOM flag set). ATPTimeOut indicates the length of time that ATPSndRequest should wait for a response before retransmitting the request. ATPRetries indicates the maximum number of retries ATPSndRequest should attempt. ATPXO should be TRUE if you want the request to be part of an exactly-once transaction. ATPSndRequest completes when either the transaction is completed or the retry count is exceeded. Result codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests noDataArea Too many outstanding ATP calls æKY ATPSndRsp æFp Appletalk.p æT FUNCTION æD FUNCTION ATPSndRsp(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := ATPSndRsp(abRecord,async); æMM æRI ATPSndRsp function II-294 æC ABusRecord <-- abOpcode {always tATPSdRsp} <-- abResult {result code} --> abUserReference {for your use} --> atpSocket {responding socket number} --> atpAddress {destination socket address} --> atpRspBDSPtr {pointer to response BDS} --> atpTransID {transaction ID} --> atpEOM {end-of-message flag} --> atpNumBufs {number of response packets being sent} --> atpBDSSize {number of elements in response BDS} ATPSndRsp sends a response to another socket. ATPSocket contains the socket number from which the response should be sent and atpAddress contains the internet address of the socket to which the response should be sent. ATPTransID must contain the transaction ID. ATPEOM is TRUE if the response BDS contains the final packet in a transaction composed of a group of packets and the number of packets in the response is less than expected. ATPRspBDSPtr points to the buffer data structure containing the responses to be sent. ATPBDSSize indicates the number of elements in the response BDS, and must be in the range 1 to 8. ATPNumBufs indicates the number of response packets being sent with this call, and must be in the range 0 to 8. Note: In some situations, you may want to send only part (or possibly none) of your response message back immediately. For instance, you might be requested to send back seven disk blocks, but have only enough internal memory to store one block. In this case, set atpBDSSize to 7 (total number of response packets), atpNumBufs to 0 (number of response packets currently being sent), and call ATPSndRsp. Then as you read in one block at a time, call ATPAddRsp until all seven response datagrams have been sent. During exactly-once transactions, ATPSndRsp won’t complete until the release packet is received or the release timer expires. Result codes noErr No error badATPSkt Bad responding socket noRelErr No release received sktClosed Socket closed by a cancel call noDataArea Too many outstanding ATP calls badBuffNum Bad sequence number æKY atpSTSvalue æFp Appletalk.p æC atpSTSvalue = 8; {ATP Send-Transmission-Status bit } æKY atpTIDValidvalue æFp Appletalk.p æC atpTIDValidvalue = 2; {ATP trans. ID valid bit } æKY ATPtimeOutVal æFp Appletalk.p æC ATPtimeOutVal = SREQ.timeOutVal; æKY ATPtransID æFp Appletalk.p æC ATPtransID = OTH2.transID; æKY ATPUnload æFp Appletalk.p æT FUNCTION æD FUNCTION ATPUnload: OSErr; æDT myVariable := ATPUnload; æRI ATPUnload function II-290 æC ATPUnload makes the .ATP driver purgeable; the space isn’t actually released by the Memory Manager until necessary. Note: This call applies only to a Macintosh 128K; on a Macintosh 512K or Macintosh XL, ATPUnload has no effect. Result codes noErr No error æKY ATPuserData æFp Appletalk.p æC ATPuserData = ATP.userData; æKY atpXOvalue æFp Appletalk.p æC atpXOvalue = 32; {ATP exactly-once bit } æKY BDSElement,BDSType,BDSPtr æFp AppleTalk.p æT RECORD æC BDSPtr = ^BDSType; BDSType = ARRAY [0..7] OF BDSElement; BDSElement = RECORD buffSize: INTEGER; buffPtr: Ptr; dataSize: INTEGER; userBytes: LONGINT; END; æKY BitMapType æFp AppleTalk.p æT TYPE æC BitMapType = PACKED ARRAY [0..7] OF BOOLEAN; æKY BuildBDS æFp Appletalk.p æT FUNCTION æD FUNCTION BuildBDS(buffPtr: Ptr;bdsPtr: Ptr;buffSize: INTEGER): INTEGER; æDT myVariable := BuildBDS(buffPtr,bdsPtr,buffSize); æRI BuildBDS function V-515 æC This routine builds a BDS, for use with the ATP calls. Given a data buffer of length buffSize pointed to by buffPtr, it fills in the BDS pointed to by bdsPtr. The buffer will be broken up into pieces of maximum size (578 bytes). The user bytes in the BDS are not modified by this routine. This routine is provided only as a convenience; generally the caller will be able to build the BDS completely from Pascal without it. æKY BuildDDPwds æFp Appletalk.p æT PROCEDURE æD PROCEDURE BuildDDPwds(wdsPtr: Ptr;headerPtr: Ptr;dataPtr: Ptr;netAddr: AddrBlock; ddpType: INTEGER;dataLen: INTEGER); æDT BuildDDPwds(wdsPtr,headerPtr,dataPtr,netAddr,ddpType,dataLen); æRI BuildDDPwds procedure V-514 æC This routine builds a single-frame write data structure DDP WDS, for use with the PWriteDDP call. Given a header buffer of at least 17 bytes pointed to by headerPtr and a data buffer of length dataLen pointed to by dataPtr, it fills in the WDS pointed to by wdsPtr, and sets the destination address and protocol type as indicated by destaddress and DDPtype, respectively. The WDS indicated must contain at least 3 elements. æKY BuildLAPwds æFp Appletalk.p æT PROCEDURE æD PROCEDURE BuildLAPwds(wdsPtr: Ptr;dataPtr: Ptr;destHost: INTEGER;prototype: INTEGER; frameLen: INTEGER); æDT BuildLAPwds(wdsPtr,dataPtr,destHost,prototype,frameLen); æRI BuildLAPwds procedure V-514 æC This routine builds a single-frame write data structure LAP WDS for use with the PWriteLAP call. Given a buffer of length frameLen pointed to by dataPtr, it fills in the WDS pointed to by wdsPtr and sets the destination node and protocol type as indicated by destHost and protoType, respectively. The WDS indicated must contain at least two elements. æKY DDPchecksumFlag æFp Appletalk.p æC DDPchecksumFlag = DDP.checksumFlag; æKY DDPCloseSocket æFp Appletalk.p æT FUNCTION æD FUNCTION DDPCloseSocket(theSocket: Byte): OSErr; æDT myVariable := DDPCloseSocket(theSocket); æMM æRI DDPCloseSocket function II-282 æC DDPCloseSocket removes the entry of the specified socket from the socket table and cancels all pending DDPRead calls that have been made for that socket. If you pass a socket number of 0, or if you attempt to close a socket that isn’t open, DDPCloseSocket will return ddpSktErr. Result codes noErr No error ddpSktErr Socket error æKY DDPlistener æFp Appletalk.p æC DDPlistener = DDP.DDPptrs.listener; æKY DDPOpenSocket æFp Appletalk.p æT FUNCTION æD FUNCTION DDPOpenSocket(VAR theSocket: Byte;sktListener: Ptr): OSErr; æDT myVariable := DDPOpenSocket(theSocket,sktListener); æMM æRI DDPOpenSocket function II-282 æC DDPOpenSocket adds a socket and its socket listener to the socket table. If theSocket is nonzero, it must be in the range 64 to 127, and it specifies the socket’s number; if theSocket is 0, DDPOpenSocket dynamically assigns a socket number in the range 128 to 254, and returns it in theSocket. SktListener contains a pointer to the socket listener; if it’s NIL, the default listener will be used. If you’re using the default socket listener, you must then call DDPRead to receive a datagram (in order to specify buffer space for the default socket listener). If, however, you’ve written your own socket listener and sktListener points to it, your listener will provide buffers for receiving datagrams and you shouldn’t use DDPRead calls. DDPOpenSocket will return ddpSktErr if you pass the number of an already opened socket, if you pass a socket number greater than 127, or if the socket table is full. Note: The range of static socket numbers 1 through 63 is reserved by Apple for internal use. Socket numbers 64 through 127 are available for unrestricted experimental use. Result codes noErr No error ddpSktErr Socket error æKY DDPRdCancel æFp Appletalk.p æT FUNCTION æD FUNCTION DDPRdCancel(abRecord: ABRecHandle): OSErr; æDT myVariable := DDPRdCancel(abRecord); æMM æRI DDPRdCancel function II-284 æC Given the handle to the ABusRecord of a previously made DDPRead call, DDPRdCancel dequeues the DDPRead call, provided that a packet satisfying the DDPRead hasn’t already arrived. DDPRdCancel returns noErr if the DDPRead call is successfully removed from the queue. If DDPRdCancel returns recNotFnd, check the abResult field of abRecord to verify that the DDPRead has been completed and determine its outcome. Result codes noErr No error readQErr Invalid socket or socket not found in table recNotFnd ABRecord not found in queue »Example This example sends a DDP packet synchronously and waits asynchronously for a response. Assume that both nodes are using a known socket number (in this case, 30) to receive packets. Normally, you would want to use NBP to look up your destination’s socket address. VAR myABRecord: ABRecHandle; myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive} mySocket: Byte; errCode, index, dataLen: INTEGER; someText: Str255; async, retCksumErrs, doChecksum: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(ddpSize)); mySocket := 30; {Add mySocket to socket table and install default socket listener to service } { datagrams addressed to that socket. No packets addressed to mySocket will be } { received until we call DDPRead. } errCode := DDPOpenSocket(mySocket, NIL); IF errCode <> noErr THEN WRITELN('Error while opening the socket') {Have we opened too many socket listeners? Remember that DDP uses two of } { them.} ELSE BEGIN {Prepare data to be sent} someText := 'This is a sample datagram'; dataLen := LENGTH(someText); FOR index := 0 TO dataLen - 1 DO {stuff buffer with packet data} myBuffer[index] := someText[index + 1]; async := FALSE; WITH myABRecord^^ DO {fill the parameters in the ABusRecord} BEGIN ddpType := 5; ddpAddress.aNet := 0; {send on “our” network} ddpAddress.aNode := 34; ddpAddress.aSocket := mySocket; ddpReqCount := dataLen; ddpDataPtr := @myBuffer; END; doChecksum := FALSE; {If packet contains a DDP long header, compute checksum and insert it into } { the header.} errCode := DDPWrite(myABRecord, doChecksum, async); {send packet} {In the case of a sync call, errCode and the abResult field of myABRecord } { will contain the same result code. We can also reuse myABRecord, since we } { know whether the call has completed.} IF errCode <> noErr THEN WRITELN('Error while writing out the packet') {Maybe the receiving node wasn't on-line} ELSE BEGIN {We have sent out the packet and are now waiting for a response. We } { issue an async DDPRead call so that we don't “hang” waiting for a } { response that may not come. To cancel the async read call, we must } { close the socket associated with the call or call DDPRdCancel.} async := TRUE; retCksumErrs := TRUE; {return packets even if } { they have a checksum error} WITH myABRecord^^ DO BEGIN ddpSocket := mySocket; ddpReqCount := 600; {our reception buffer is max size} ddpDataPtr := @myBuffer; END; {Wait for a packet asynchronously} errCode := DDPRead(myABRecord, retCksumErrs, async); IF errCode <> noErr THEN WRITELN('Error while trying to queue up a DDPRead') {Was the socket listener installed correctly?} ELSE BEGIN {We can either sit here in a loop and poll the } { abResult field or just exit our code and use the } { event mechanism to flag us when the packet arrives.} CheckForMyEvent; {your procedure for checking for a } { network event} {If there were no errors, a packet is inside the array } { mybuffer, the length is in ddpActCount, and the } { address of the sending socket is in ddpAddress. } { Process the packet received here and report any errors.} errCode := DDPCloseSocket(mySocket); {we're done with it} IF errCode <> noErr THEN WRITELN('Error while closing the socket'); END; END; END; END; END. æKY DDPRead æFp Appletalk.p æT FUNCTION æD FUNCTION DDPRead(abRecord: ABRecHandle;retCksumErrs: BOOLEAN;async: BOOLEAN): OSErr; æDT myVariable := DDPRead(abRecord,retCksumErrs,async); æMM æRI DDPRead function II-283 æC ABusRecord <-- abOpcode {always tDDPRead} <-- abResult {result code} --> abUserReference {for your use} <-- ddpType {DDP protocol type} --> ddpSocket {listening socket number} <-- ddpAddress {source socket address} --> ddpReqCount {buffer size in bytes} <-- ddpActCount {number of bytes actually received} --> ddpDataPtr {pointer to buffer} <-- ddpNodeID {original destination node ID} DDPRead receives a datagram from another socket. The size and location of the buffer that will receive the data are specified by ddpReqCount and ddpDataPtr. If the buffer isn’t large enough to hold all of the incoming frame data, the extra bytes will be discarded and buf2SmallErr will be returned. The number of bytes actually received is returned in ddpActCount. DDPSocket specifies the socket to receive the datagram (the “listening” socket). The node to which the packet was sent is returned in ddpNodeID; if the packet was broadcast ddpNodeID will contain 255. The address of the socket that sent the packet is returned in ddpAddress. If retCksumErrs is FALSE, DDPRead will discard any packets received with an invalid checksum and inform the caller of the error. If retCksumErrs is TRUE, DDPRead will deliver all packets, whether or not the checksum is valid; it will also notify the caller when there’s a checksum error. Note: The sender of the datagram must be in a different node from the receiver. You should issue DDPRead calls only for receiving datagrams for sockets opened with the default socket listener; see the description of DDPOpenSocket. Note: If the buffer provided isn’t large enough to hold all of the incoming frame data (buf2SmallErr), the checksum can’t be calculated; in this case, DDPRead will deliver packets even if retCksumErrs is FALSE. Result codes noErr No error buf2SmallErr Datagram too large for buffer cksumErr Checksum error ddpLenErr Datagram length too big ddpSktErr Socket error readQErr Invalid socket or socket not found in table æKY DDPsocket æFp Appletalk.p æC DDPsocket = DDP.socket; æKY DDPwdsPointer æFp Appletalk.p æC DDPwdsPointer = DDP.DDPptrs.wdsPointer; æKY DDPWrite æFp Appletalk.p æT FUNCTION æD FUNCTION DDPWrite(abRecord: ABRecHandle;doChecksum: BOOLEAN;async: BOOLEAN): OSErr; æDT myVariable := DDPWrite(abRecord,doChecksum,async); æMM æRI DDPWrite function II-283 æC ABusRecord <-- abOpcode {always tDDPWrite} <-- abResult {result code} --> abUserReference {for your use} --> ddpType {DDP protocol type} --> ddpSocket {source socket number} --> ddpAddress {destination socket address} --> ddpReqCount {length of datagram data} --> ddpDataPtr {pointer to buffer} DDPWrite sends a datagram to another socket. DDPReqCount and ddpDataPtr specify the length and location of the data to send. The ddpType field indicates the DDP protocol type of the frame, and ddpAddress is the complete internet address of the socket to which the datagram should be sent. DDPSocket specifies the socket from which the datagram should be sent. Datagrams sent over the internet to a node on an AppleTalk network different from the sending node’s network have an optional software checksum to detect errors that might occur inside the intermediate bridges. If doChecksum is TRUE, DDPWrite will compute this checksum; if it’s FALSE, this software checksum feature is ignored. Note: The destination socket can’t be in the same node as the program making the DDPWrite call. Result codes noErr No error ddpLenErr Datagram length too big ddpSktErr Source socket not open noBridgeErr No bridge found æKY EntityName æFp AppleTalk.p æT RECORD æC EntityName = RECORD objStr: Str32; typeStr: Str32; zoneStr: Str32; END; { Real definition of EntityName is 3 PACKED strings of any length (32 is just an example). No offsets for Asm since each String address must be calculated by adding length byte to last string ptr. In Pascal, String(32) will be 34 bytes long since fields never start on an odd byte unless they are only a byte long. So this will generate correct looking interfaces for Pascal and C, but they will not be the same, which is OK since they are not used. } æKY EntityPtr æFp AppleTalk.p æT TYPE æC EntityPtr = ^EntityName; EntityName = RECORD objStr: Str32; typeStr: Str32; zoneStr: Str32; END; { Real definition of EntityName is 3 PACKED strings of any length (32 is just an example). No offsets for Asm since each String address must be calculated by adding length byte to last string ptr. In Pascal, String(32) will be 34 bytes long since fields never start on an odd byte unless they are only a byte long. So this will generate correct looking interfaces for Pascal and C, but they will not be the same, which is OK since they are not used. } æKY GetBridgeAddress æFp Appletalk.p æT FUNCTION æD FUNCTION GetBridgeAddress: INTEGER; æDT myVariable := GetBridgeAddress; æRT 132 æRI GetBridgeAddress function V-515, N132-2 æC This routine returns the current address of a bridge in the low byte, or zero if there is none. æKY GetNodeAddress æFp Appletalk.p æT FUNCTION æD FUNCTION GetNodeAddress(VAR myNode: INTEGER;VAR myNet: INTEGER): OSErr; æDT myVariable := GetNodeAddress(myNode,myNet); æRI GetNodeAddress function II-303 æC GetNodeAddress returns the current node ID and network number of the caller. If the .MPP driver isn’t installed, it returns noMPPErr. If myNet contains 0, this means that a bridge hasn’t yet been found. Result codes noErr No error noMPPErr MPP driver not installed æKY IsATPOpen æFp Appletalk.p æT FUNCTION æD FUNCTION IsATPOpen: BOOLEAN; æDT myVariable := IsATPOpen; æRI IsATPOpen function II-304 æC [Not in ROM] IsATPOpen returns TRUE if the .ATP driver is loaded and running. æKY IsMPPOpen æFp Appletalk.p æT FUNCTION æD FUNCTION IsMPPOpen: BOOLEAN; æDT myVariable := IsMPPOpen; æRI IsMPPOpen function II-304 æC [Not in ROM] IsMPPOpen returns TRUE if the .MPP driver is loaded and running. æKY LAPAdrBlock æFp AppleTalk.p æT PACKED RECORD æC LAPAdrBlock = PACKED RECORD dstNodeID: Byte; srcNodeID: Byte; lapProtType: ABByte; END; æKY LAPCloseProtocol æFp Appletalk.p æT FUNCTION æD FUNCTION LAPCloseProtocol(theLAPType: ABByte): OSErr; æDT myVariable := LAPCloseProtocol(theLAPType); æMM æRI LAPCloseProtocol function II-277 æC LAPCloseProtocol removes from the node’s protocol table the specified ALAP protocol type, as well as its protocol handler. Warning: Don’t close ALAP protocol type values 1 or 2. If you close these protocol types, DDP will be disabled; once disabled, the only way to restore DDP is to restart the system, or to close and then reopen AppleTalk. Result codes noErr No error lapProtErr Error detaching protocol type æKY LAPhandler æFp Appletalk.p æC LAPhandler = LAP.LAPptrs.handler; æKY LAPOpenProtocol æFp Appletalk.p æT FUNCTION æD FUNCTION LAPOpenProtocol(theLAPType: ABByte;protoPtr: Ptr): OSErr; æDT myVariable := LAPOpenProtocol(theLAPType,protoPtr); æMM æRI LAPOpenProtocol function II-277 æC LAPOpenProtocol adds the ALAP protocol type specified by theLAPType to the node’s protocol table. If you provide a pointer to a protocol handler in protoPtr, ALAP will send each frame with an ALAP protocol type of theLAPType to that protocol handler. If protoPtr is NIL, the default protocol handler will be used for receiving frames with an ALAP protocol type of theLAPType. In this case, to receive a frame you must call LAPRead to provide the default protocol handler with a buffer for placing the data. If, however, you’ve written your own protocol handler and protoPtr points to it, your protocol handler will have the responsibility for receiving the frame and it’s not necessary to call LAPRead. Result codes noErr No error lapProtErr Error attaching protocol type æKY LAPprotType æFp Appletalk.p æC LAPprotType = LAP.protType; æKY LAPRdCancel æFp Appletalk.p æT FUNCTION æD FUNCTION LAPRdCancel(abRecord: ABRecHandle): OSErr; æDT myVariable := LAPRdCancel(abRecord); æMM æRI LAPRdCancel function II-279 æC Given the handle to the ABusRecord of a previously made LAPRead call, LAPRdCancel dequeues the LAPRead call, provided that a packet satisfying the LAPRead has not already arrived. LAPRdCancel returns noErr if the LAPRead call is successfully removed from the queue. If LAPRdCancel returns recNotFnd, check the abResult field to verify that the LAPRead has been completed and determine its outcome. Result codes noErr No error readQErr Invalid protocol type or protocol type not found in table recNotFnd ABRecord not found in queue »Example This example sends an ALAP packet synchronously and waits asynchronously for a response. Assume that both nodes are using a known protocol type (in this case, 73) to receive packets, and that the destination node has a node ID of 4. VAR myABRecord: ABRecHandle; myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive} myLAPType: Byte; errCode, index, dataLen: INTEGER; someText: Str255; async: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(lapSize)); myLAPType := 73; {Enter myLAPType into protocol handler table and install default handler to } { service frames of that ALAP type. No packets of that ALAP type will be } { received until we call LAPRead.} errCode := LAPOpenProtocol(myLAPType, NIL); IF errCode <> noErr THEN WRITELN('Error while opening the protocol type') {Have we opened too many protocol types? Remember that DDP uses two of } { them.} ELSE BEGIN {Prepare data to be sent} someText := 'This data will be in the ALAP data area'; {The .MPP implementation requires that the first two bytes of the ALAP } { data field contain the length of the data, including the length bytes } { themselves.} dataLen := LENGTH(someText) + 2; buffer[0] := CHR(dataLen DIV 256); {high byte of data length} buffer[1] := CHR(dataLen MOD 256); {low byte of data length} FOR index := 1 TO dataLen - 2 DO {stuff buffer with packet data} buffer[index + 1] := someText[index]; async := FALSE; WITH myABRecord^^ DO {fill parameters in the ABusRecord} BEGIN lapAddress.lapProtType := myLAPType; lapAddress.dstNodeID := 4; lapReqCount := dataLen; lapDataPtr := @buffer; END; {Send the frame} errCode := LAPWrite(myABRecord, async); {In the case of a sync call, errCode and the abResult field of } { the myABRecord will contain the same result code. We can also } { reuse myABRecord, since we know whether the call has completed.} IF errCode <> noErr THEN WRITELN('Error while writing out the packet') {Maybe the receiving node wasn't on-line} ELSE BEGIN {We have sent out the packet and are now waiting for a response. We } { issue an async LAPRead call so that we don't “hang” waiting for a } { response that may not come.} async := TRUE; WITH myABRecord^^ DO BEGIN lapAddress.lapProtType := myLAPType; {ALAP type we want to receive } lapReqCount := 600; {our buffer is maximum size} lapDataPtr := @buffer; END; errCode := LAPRead(myABRecord, async); {wait for a packet} IF errCode <> noErr THEN WRITELN('Error while trying to queue up a LAPRead') {Was the protocol handler installed correctly?} ELSE BEGIN {We can either sit here in a loop and poll the abResult } { field or just exit our code and use the event } { mechanism to flag us when the packet arrives.} CheckForMyEvent; {your procedure for checking for a network event} errCode := LAPCloseProtocol(myLAPType); IF errCode <> noErr THEN WRITELN('Error while closing the protocol type'); END; END; END; END; END. æKY LAPRead æFp Appletalk.p æT FUNCTION æD FUNCTION LAPRead(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := LAPRead(abRecord,async); æMM æRI LAPRead function II-278 æC ABusRecord <-- abOpcode {always tLAPRead} <-- abResult {result code} --> abUserReference {for your use} <-- lapAddress.dstNodeID {destination node ID} <-- lapAddress.srcNodeID {source node ID} --> lapAddress.lapProtType {ALAP protocol type} --> lapReqCount {buffer size in bytes} <-- lapActCount {number of frame data bytes actually received} --> lapDataPtr {pointer to buffer} LAPRead receives a frame from another node. LAPReqCount and lapDataPtr specify the size and location of the buffer that will receive the frame data. If the buffer isn’t large enough to hold all of the incoming frame data, the extra bytes will be discarded and buf2SmallErr will be returned. The number of bytes actually received is returned in lapActCount. Only frames with ALAP protocol type equal to lapAddress.lapProtType will be received. The node IDs of the frame’s source and destination nodes are returned in lapAddress.srcNodeID and lapAddress.dstNodeID. You can determine whether the packet was broadcast to you by examining the value of lapAddress.dstNodeID—if the packet was broadcast it’s equal to 255, otherwise it’s equal to your node ID. Note: You should issue LAPRead calls only for ALAP protocol types that were opened (via LAPOpenProtocol) to use the default protocol handler. Warning: If you close a protocol type for which there are still LAPRead calls pending, the calls will be canceled but the memory occupied by their ABusRecords will not be released. For this reason, before closing a protocol type, call LAPRdCancel to cancel any pending LAPRead calls associated with that protocol type. Result codes noErr No error buf2SmallErr Frame too large for buffer readQErr Invalid protocol type or protocol type not found in table æKY lapSize,ddpSize,nbpSize,atpSize æFp Appletalk.p æC lapSize = 20; {ABusRecord size for ALAP} ddpSize = 26; {ABusRecord size for DDP} nbpSize = 26; {ABusRecord size for NBP} atpSize = 56; {ABusRecord size for ATP} æKY LAPwdsPointer æFp Appletalk.p æC LAPwdsPointer = LAP.LAPptrs.wdsPointer; æKY LAPWrite æFp Appletalk.p æT FUNCTION æD FUNCTION LAPWrite(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := LAPWrite(abRecord,async); æMM æRI LAPWrite function II-277 æC ABusRecord <-- abOpcode {always tLAPWrite} <-- abResult {result code} --> abUserReference {for your use} --> lapAddress.dstNodeID {destination node ID} --> lapAddress.lapProtType {ALAP protocol type} --> lapReqCount {length of frame data} --> lapDataPtr {pointer to frame data} LAPWrite sends a frame to another node. LAPReqCount and lapDataPtr specify the length and location of the data to send. The lapAddress.lapProtType field indicates the ALAP protocol type of the frame and the lapAddress.dstNodeID indicates the node ID of the node to which the frame should be sent. Note: The first two bytes of an ALAP frame’s data must contain the length in bytes of that data, including the length bytes themselves. Result codes noErr No error excessCollsns Unable to contact destination node; packet not sent ddpLenErr ALAP data length too big lapProtErr Invalid ALAP protocol type æKY MPPClose æFp Appletalk.p æT FUNCTION æD FUNCTION MPPClose: OSErr; æDT myVariable := MPPClose; æMM æRI MPPClose function II-275 æC MPPClose removes the .MPP driver, and any data structures associated with it, from memory. If the .ATP driver or NBP code were also installed, they’re removed as well. MPPClose also returns the use of port B to the Serial Driver. Warning: Since other co-resident programs may be using AppleTalk, it’s strongly recommended that you never use this call. MPPClose will completely disable AppleTalk; the only way to restore AppleTalk is to call MPPOpen again. æKY MPPcsCode æFp Appletalk.p æC MPPcsCode = MPP.csCode; æKY MPPioCompletion æFp Appletalk.p æC MPPioCompletion = MPP.ioCompletion; æKY MPPioRefNum æFp Appletalk.p æC MPPioRefNum = MPP.ioRefNum; æKY MPPioResult æFp Appletalk.p æC MPPioResult = MPP.ioResult; æKY MPPOpen æFp Appletalk.p æT FUNCTION æD FUNCTION MPPOpen: OSErr; æDT myVariable := MPPOpen; æMM æRT 224 æRI MPPOpen function II-275 æC MPPOpen first checks whether the .MPP driver has already been loaded; if it has, MPPOpen does nothing and returns noErr. If MPP hasn’t been loaded, MPPOpen attempts to load it into the system heap. If it succeeds, it then initializes the driver’s variables and goes through the process of dynamically assigning a node ID to that Macintosh. On a Macintosh 512K or XL, it also loads the .ATP driver and NBP code into the system heap. If serial port B isn’t configured for AppleTalk, or is already in use, the .MPP driver isn’t loaded and an appropriate result code is returned. Result codes noErr No error portInUse Port B is already in use portNotCf Port B not configured for AppleTalk æKY NamesTableEntry æFp AppleTalk.p æT RECORD æC NamesTableEntry = RECORD qLink: QElemPtr; nteAddress: AddrBlock; nteData: PACKED ARRAY [1..100] OF CHAR; END; æKY NBPConfirm æFp Appletalk.p æT FUNCTION æD FUNCTION NBPConfirm(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := NBPConfirm(abRecord,async); æMM æRT 9 æRI NBPConfirm function II-301, N9-2 æC ABusRecord <-- abOpcode {always tNBPConfirm} <-- abResult {result code} --> abUserReference {for your use} --> nbpEntityPtr {pointer to entity name} <-- nbpDataField {socket number} --> nbpAddress {socket address} --> nbpRetransmitInfo {retransmission information} NBPConfirm confirms that an entity known by name and address still exists (is still entered in the names directory). NBPEntityPtr points to a variable of type EntityName that contains the name to confirm, and nbpAddress specifies the address to be confirmed. (No meta-characters are allowed in the entity name.) NBPRetransmitInfo contains the retry interval and the retry count. The socket number of the entity is returned in nbpDataField. NBPConfirm is more efficient than NBPLookup in terms of network traffic. Result codes noErr No error nbpConfDiff Name confirmed for different socket nbpNoConfirm Name not confirmed æKY NBPconfirmAddr æFp Appletalk.p æC NBPconfirmAddr = NBP.parm.Confirm.confirmAddr; æKY NBPcount æFp Appletalk.p æC NBPcount = NBP.count; æKY NBPentityPtr æFp Appletalk.p æC NBPentityPtr = NBP.NBPPtrs.entityPtr; æKY NBPExtract æFp Appletalk.p æT FUNCTION æD FUNCTION NBPExtract(theBuffer: Ptr;numInBuf: INTEGER;whichOne: INTEGER; VAR abEntity: EntityName;VAR address: AddrBlock): OSErr; æDT myVariable := NBPExtract(theBuffer,numInBuf,whichOne,abEntity,address); æMM æRI NBPExtract function II-300,V-515 æC This routine is provided in the alternate interface, but can be used as provided for extracting NBP entity names from a look-up response buffer. NBPExtract returns one address from the list of addresses returned by NBPLookup. TheBuffer and numInBuf indicate the location and number of tuples in the buffer. WhichOne specifies which one of the tuples in the buffer should be returned in the abEntity and address parameters. Result codes noErr No error extractErr Can’t find tuple in buffer æKY NBPinterval æFp Appletalk.p æC NBPinterval = NBP.interval; æKY NBPLoad æFp Appletalk.p æT FUNCTION æD FUNCTION NBPLoad: OSErr; æDT myVariable := NBPLoad; æMM æRI NBPLoad function II-301 æC On a Macintosh 128K, NBPLoad reads the NBP code from the system resource file into the application heap. On a Macintosh 512K or XL, NBPLoad has no effect since the NBP code should have already been loaded when the .MPP driver was opened. Normally you’ll never need to call NBPLoad, because the AppleTalk Manager calls it when necessary. Result codes noErr No error æKY NBPLookup æFp Appletalk.p æT FUNCTION æD FUNCTION NBPLookup(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := NBPLookup(abRecord,async); æMM æRT 9, 20 æRI NBPLookup function II-300, N9-1, 2, N20-2 æC ABusRecord <-- abOpcode {always tNBPLookup} <-- abResult {result code} --> abUserReference {for your use} --> nbpEntityPtr {pointer to entity name} --> nbpBufPtr {pointer to buffer} --> nbpBufSize {buffer size in bytes} <-> nbpDataField {number of addresses received} --> nbpRetransmitInfo {retransmission information} NBPLookup returns the addresses of all entities with a specified name. NBPEntityPtr points to a variable of type EntityName containing the name of the entity whose address should be returned. (Meta-characters are allowed in the entity name.) NBPBufPtr and nbpBufSize contain the location and size of an area of memory in which the entity names and their corresponding addresses should be returned. NBPDataField indicates the maximum number of matching names to find addresses for; the actual number of addresses found is returned in nbpDataField. NBPRetransmitInfo contains the retry interval and the retry count. When specifying nbpBufSize, for each NBP tuple expected, allow space for the actual characters of the name, the address, and four bytes for use by NBP. Result codes noErr No error nbpBuffOvr Buffer overflow æKY NBPmaxToGet æFp Appletalk.p æC NBPmaxToGet = NBP.parm.Lookup.maxToGet; æKY NBPnewSocket æFp Appletalk.p æC NBPnewSocket = NBP.parm.Confirm.newSocket; æKY NBPnKillQEl æFp Appletalk.p æC NBPnKillQEl = NBPKILL.nKillQEl; æKY NBPntQElPtr æFp Appletalk.p æC NBPntQElPtr = NBP.NBPPtrs.ntQElPtr; æKY NBPnumGotten æFp Appletalk.p æC NBPnumGotten = NBP.parm.Lookup.numGotten; æKY NBPRegister æFp Appletalk.p æT FUNCTION æD FUNCTION NBPRegister(abRecord: ABRecHandle;async: BOOLEAN): OSErr; æDT myVariable := NBPRegister(abRecord,async); æMM æRT 20 æRI NBPRegister function II-299, N20-2 æC ABusRecord <-- abOpcode {always tNBPRegister} <-- abResult {result code} --> abUserReference {for your use} --> nbpEntityPtr {pointer to entity name} --> nbpBufPtr {pointer to buffer} --> nbpBufSize {buffer size in bytes} --> nbpAddress.aSocket {socket address} --> nbpRetransmitInfo {retransmission information} NBPRegister adds the name and address of an entity to the node’s names table. NBPEntityPtr points to a variable of type EntityName containing the entity’s name. If the name is already registered, NBPRegister returns the result code nbpDuplicate. NBPAddress indicates the socket for which the name should be registered. NBPBufPtr and nbpBufSize specify the location and size of a buffer for NBP to use internally. While the variable of type EntityName is declared as three 32-byte strings, only the actual characters of the name are placed in the buffer pointed to by nbpBufPtr. For this reason, nbpBufSize needs only to be equal to the actual length of the name, plus an additional 12 bytes for use by NBP. Warning: This buffer must not be altered or released until the name is removed from the names table via an NBPRemove call. If you allocate the buffer through a NewHandle call, you must lock it as long as the name is registered. Warning: The zone field of the entity name must be set to the meta-character “*”. Result codes noErr No error nbpDuplicate Duplicate name already exists æKY NBPRemove æFp Appletalk.p æT FUNCTION æD FUNCTION NBPRemove(abEntity: EntityPtr): OSErr; æDT myVariable := NBPRemove(abEntity); æMM æRI NBPRemove function II-301 æC NBPRemove removes an entity name from the names table of the given entity’s node. Result codes noErr No error nbpNotFound Name not found æKY NBPretBuffPtr æFp Appletalk.p æC NBPretBuffPtr = NBP.parm.Lookup.retBuffPtr; æKY NBPretBuffSize æFp Appletalk.p æC NBPretBuffSize = NBP.parm.Lookup.retBuffSize; æKY NBPSetEntity æFp Appletalk.p æT PROCEDURE æD PROCEDURE NBPSetEntity(buffer: Ptr;nbpObject: Str32;nbpType: Str32;nbpZone: Str32); æDT NBPSetEntity(buffer,nbpObject,nbpType,nbpZone); æRI NBPSetEntity procedure V-514 æC This routine builds an NBP entity structure, for use with the PLookupNBP and PConfirmName calls. Given a buffer of at least the size of the EntityName data structure (99 bytes) pointed to by buffer, this routine sets the indicated object, type, and zone in that buffer. æKY NBPSetNTE æFp Appletalk.p æT PROCEDURE æD PROCEDURE NBPSetNTE(ntePtr: Ptr;nbpObject: Str32;nbpType: Str32;nbpZone: Str32; socket: INTEGER); æDT NBPSetNTE(ntePtr,nbpObject,nbpType,nbpZone,socket); æRI NBPSetNTE procedure V-515 æC This routine builds an NBP names table entry, for use with the PRegisterName call. Given a names table entry of at least the size of the EntityName data structure plus nine bytes (108 bytes) pointed to by ntePtr, this routine sets the indicated object, type, zone, and socket in that names table entry. æKY NBPUnload æFp Appletalk.p æT FUNCTION æD FUNCTION NBPUnload: OSErr; æDT myVariable := NBPUnload; æMM æRI NBPUnload function II-301 æC On a Macintosh 128K, NBPUnload makes the NBP code purgeable; the space isn’t actually released by the Memory Manager until necessary. On a Macintosh 512K or Macintosh XL, NBPUnload has no effect. Result codes noErr No error »Example This example of NBP registers our node as a print spooler, searches for any print spoolers registered on the network, and then extracts the information for the first one found. CONST mySocket = 20; VAR myABRecord: ABRecHandle; myEntity: EntityName; entityAddr: AddrBlock; nbpNamePtr: Ptr; myBuffer: PACKED ARRAY [0..999] OF CHAR; errCode: INTEGER; async: BOOLEAN; BEGIN errCode := MPPOpen; IF errCode <> noErr THEN WRITELN('Error in opening AppleTalk') {Maybe serial port B isn't available for use by AppleTalk} ELSE BEGIN {Call Memory Manager to allocate ABusRecord} myABRecord := ABRecHandle(NewHandle(nbpSize)); {Set up our entity name to register} WITH myEntity DO BEGIN objStr := 'Gene Station'; {we are called 'Gene Station' } typeStr := 'PrintSpooler'; { and are of type 'PrintSpooler'} zoneStr := '*'; {Allocate data space for the entity name (used by NBP)} nbpNamePtr := NewPtr(LENGTH(objStr) + LENGTH(typeStr) + LENGTH(zoneStr) + 12); END; {Set up the ABusRecord for the NBPRegister call} WITH myABRecord^^ DO BEGIN nbpEntityPtr := @myEntity; nbpBufPtr := nbpNamePtr; {buffer used by NBP internally} nbpBufSize := nbpNameBufSize; nbpAddress.aSocket := mySocket; {socket to register us on} nbpRetransmitInfo.retransInterval := 8; {retransmit every 64 } nbpRetransmitInfo.retransCount := 3; { ticks and try 3 times} END; async := FALSE; errCode := NBPRegister(myABRecord, async); IF errCode <> noErr THEN WRITELN('Error occurred in the NBPRegister call') {Maybe the name is already registered somewhere else on the } { network.} ELSE BEGIN {Now that we've registered our name, find others of type } { 'PrintSpooler'.} WITH myEntity DO BEGIN objStr := '='; {any one of type } typeStr := 'PrintSpooler'; { “PrintSpooler” } zoneStr := '*'; { in our zone} END; WITH myABRecord^^ DO BEGIN nbpEntityPtr := @myEntity; nbpBufPtr := @myBuffer; {buffer to place responses in} nbpBufSize := SIZEOF(myBuffer); {The field nbpDataField, before the NBPLookup call, represents an } { approximate number of responses. After the call, nbpDataField } { contains the actual number of responses received.} nbpDataField := 100; {we want about 100 responses back} END; errCode := NBPLookup(myABRecord, async); {make sync call} IF errCode <> noErr THEN WRITELN('An error occurred in the NBPLookup') {Did the buffer overflow?} ELSE BEGIN {Get the first reply} errCode := NBPExtract(@mybuffer, myABRecord^^.nbpDataField, 1, myEntity, entityAddr); {The socket address and name of the entity are returned here. If we } { want all of them, we'll have to loop for each one in the buffer.} IF errCode <> noErr THEN WRITELN('Error in NBPExtract'); {Maybe the one we wanted wasn't in the buffer} END; END; END; END. æKY NBPverifyFlag æFp Appletalk.p æC NBPverifyFlag = NBP.parm.verifyFlag; æKY OpenXPP æFp Appletalk.p æT FUNCTION æD FUNCTION OpenXPP(VAR xppRefnum: INTEGER): OSErr; æDT myVariable := OpenXPP(xppRefnum); æC »Opening the .XPP Driver To open the .XPP driver, issue a Device Manager Open call. (Refer to the Device Manager chapter.) The name of the .XPP driver is '.XPP'. The original Macintosh ROMs require that .XPP be opened only once. With new ROMs, the .XPP unit number can always be obtained through an Open call. With old ROMs only, the .XPP unit number must be hard coded to XPPUnitNum (40) since only one Open call can be issued to the driver. The .XPP driver cannot be opened unless AppleTalk is open. The application must ensure that the .MPP and .ATP drivers are opened, as described earlier in this chapter. The xppLoaded bit (bit 5) in the PortBUse byte in low memory indicates whether or not the .XPP driver is open. »Example The following is an example of the procedure an application might use to open the .XPP driver. ; Routine: OpenXPP ; ; Open the .XPP driver and return the driver refNum for it. ; ; Exit: D0 = error code (ccr's set) ; D1 = XPP driver refNum (if no errors) ; ; All other registers preserved ; xppUnitNum EQU 40 ;default XPP driver number xppTfRNum EQU -(xppUnitNum+1) ;default XPP driver refNum OpenXPP MOVE.L A0-A1/D2,-(SP) ;save registers MOVE ROM85,D0 ;check ROM type byte BPL.S @10 ;branch if >=128K ROMs BTST #xppLoadedBit,PortBUse ;is the XPP driver open already? BEQ.S @10 ;if not open, then branch to Open code MOVE #xppTfRNum,D1 ;else use this as driver refnum MOVEQ #0,D0 ;set noErr BRA.S @90 ;and exit ; ; XPP driver not open. Make an _Open call to it. If using a 128K ; ROM machine and the driver is already open, we will make another ; Open call to it just so we get the correct driver refNum. ; @10 SUB #ioQElSize,SP ;allocate temporary param block MOVE.L SP,A0 ;A0 -> param block LEA XPPName, A1 ;A1 -> XPP (ASP/AFP) driver name MOVE.L A1,ioFileName(A0) ;driver name into param block CLR.B ioPermssn(A0) ;clear permissions byte _Open MOVE ioRefNum(A0),D1 ;D1=driver refNum (invalid if error) ADD #ioQElSize,SP ;deallocate temp param block @90 MOVE.L (SP)+,A0-A1/D2 ;restore registers TST D0 ;error? (set ccr's) RTS XPPName DC.B 4 ;length of string DC.B '.XPP' ;driver name From Pascal, XPP can be opened through the OpenXPP call, which returns the driver’s reference number: FUNCTION OpenXPP (VAR xppRefnum: INTEGER) : OSErr; »Open Errors Errors returned when calling the Device Manager Open routine if the function does not execute properly include the following: • errors returned by System • portInUse is returned if the AppleTalk port is in use by a driver other than AppleTalk or if AppleTalk is not open. »Closing the .XPP Driver To close the .XPP driver, call the Device Manager Close routine. Warning: There is generally no reason to close the driver. Use this call sparingly, if at all. This call should generally be used only by system-level applications. »Close Errors Errors returned when calling the Device Manager Close routine if the function does not execute properly include the following: • errors returned by System • closeErr (new ROMs only) is returned if you try to close the driver and there are sessions active through that driver. When sessions are active, closeErr is returned and the driver remains open. • on old ROMs the driver is closed whether or not sessions are active and no error is returned. Results are unpredictable if sessions are still active. »Session Control Block The session control block (SCB) is a nonrelocatable block of data passed by the caller to XPP upon session opening. XPP reserves this block for use in maintaining an open session. The SCB size is defined by the constant scbMemSize. The SCB is a locked block, and as long as the session is open, the SCB cannot be modified in any way by the application. There is one SCB for each open session. This block can be reused once a CloseSess call is issued and completed for that session or when the session is indicated as closed. æKY PAddResponse æFp Appletalk.p æT FUNCTION æD FUNCTION PAddResponse(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PAddResponse(thePBPtr,async); æRI AddResponse function II-318,V-513 æC AddResponse function Parameter block -> 18 userData long word ;user bytes -> 26 csCode word ;always addResponse -> 28 atpSocket byte ;socket number -> 29 atpFlags byte ;control information -> 30 addrBlock long word ;response destination -> 34 reqLength word ;response size -> 36 reqPointer pointer ;pointer to response -> 44 rspNum byte ;sequence number -> 46 transID word ;transaction ID AddResponse sends an additional response packet to a socket that has already been sent the initial part of a response via SendResponse. UserData contains the four user bytes. ATPSocket contains the socket number from which the response should be sent. The end-of-message flag in atpFlags should be set if this response packet is the final packet in a transaction composed of a group of packets and the number of responses is less than requested. AddrBlock indicates the socket to which the response should be sent. ReqLength and reqPointer contain the size (in bytes) and location of the response to send; rspNum indicates the sequence number of the response (in the range 0 to 7). TransID must contain the transaction ID. Warning: If the transaction is part of an exactly-once transaction, the buffer used in the AddResponse call must not be altered or released until the corresponding SendResponse call has completed. Result codes noErr No error badATPSkt Bad responding socket noSendResp AddResponse issued before SendResponse badBuffNum Sequence number out of range noDataArea Too many outstanding ATP calls æKY PAttachPH æFp Appletalk.p æT FUNCTION æD FUNCTION PAttachPH(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PAttachPH(thePBptr,async); æRI AttachPH function II-308, V-513 æC AttachPH function Parameter block -> 26 csCode word ;always attachPH -> 28 protType byte ;ALAP protocol type -> 30 handler pointer ;protocol handler AttachPH adds the protocol handler pointed to by handler to the node's protocol table. ProtType specifies what kind of frame the protocol handler can service. After AttachPH is called, the protocol handler is called for each incoming frame whose ALAP protocol type equals protType. Result codes noErr No error lapProtErr Error attaching protocol type æKY PCloseATPSkt æFp Appletalk.p æT FUNCTION æD FUNCTION PCloseATPSkt(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PCloseATPSkt(thePBPtr,async); æRI CloseATPSkt function II-316,V-513 æC CloseATPSkt function Parameter block -> 26 csCode word ;always closeATPSkt -> 28 atpSocket byte ;socket number CloseATPSkt closes the socket whose number is specified by atpSocket, for the purpose of receiving requests. Result codes noErr No error æKY PCloseSkt æFp Appletalk.p æT FUNCTION æD FUNCTION PCloseSkt(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PCloseSkt(thePBptr,async); æRI CloseSkt function II-312,V513 æC CloseSkt function Parameter block -> 26 csCode word ;always closeSkt -> 28 socket byte ;socket number CloseSkt removes the entry of the specified socket from the socket table. If you pass a socket number of 0, or if you attempt to close a socket that isn't open, CloseSkt will return ddpSktErr. Result codes noErr No error ddpSktErr Socket error æKY PConfirmName æFp Appletalk.p æT FUNCTION æD FUNCTION PConfirmName(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PConfirmName(thePBptr,async); æRI ConfirmName function II-323,V-513 æC ConfirmName function Parameter block -> 26 csCode word ;always confirmName -> 28 interval byte ;retry interval <-> 29 count byte ;retry count -> 30 entityPtr pointer ;pointer to entity name -> 34 confirmAddr pointer ;entity address <- 38 newSocket byte ;socket number ConfirmName confirms that an entity known by name and address still exists (is still entered in the names directory). EntityPtr points to the entity's name (in the form shown in Figure 13 above). ConfirmAddr specifies the address to confirmed. No meta-characters are allowed in the entity name. Interval and count contain the retry interval and the retry count. The socket number of the entity is returned in newSocket. ConfirmName is more efficient than LookupName in terms of network traffic. Result codes noErr No error nbpConfDiff Name confirmed for different socket nbpNoConfirm Name not confirmed æKY PDetachPH æFp Appletalk.p æT FUNCTION æD FUNCTION PDetachPH(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PDetachPH(thePBptr,async); æRI DetachPH function II-308, V-513 æC DetachPH function Parameter block -> 26 csCode word ;always detachPH -> 28 protType byte ;ALAP protocol type DetachPH removes from the node's protocol table the specified ALAP protocol type and corresponding protocol handler. Result codes noErr No error lapProtErr Error detaching protocol type æKY PGetRequest æFp Appletalk.p æT FUNCTION æD FUNCTION PGetRequest(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PGetRequest(thePBPtr,async); æRI GetRequest function II-317,V-513 æC GetRequest function Parameter block <- 18 userData long word ;user bytes -> 26 csCode word ;always getRequest -> 28 atpSocket byte ;socket number <- 29 atpFlags byte ;control information <- 30 addrBlock long word ;source of request <-> 34 reqLength word ;request buffer size -> 36 reqPointer pointer ;pointer to request buffer <- 44 bitMap byte ;bit map <- 46 transID word ;transaction ID GetRequest sets up the mechanism to receive a request sent by a SendRequest call. UserData returns the four user bytes from the request. ATPSocket contains the socket number of the socket that should listen for a request. The internet address of the socket from which the request was sent is returned in addrBlock. ReqLength and reqPointer indicate the size (in bytes) and location of a buffer to store the incoming request. The actual size of the request is returned in reqLength. The transaction bit map and transaction ID will be returned in bitMap and transID. The exactly-once flag in atpFlags will be set if the request is part of an exactly-once transaction. GetRequest completes when a request is received. Result codes noErr No error badATPSkt Bad responding socket æKY PKillGetReq æFp Appletalk.p æT FUNCTION æD FUNCTION PKillGetReq(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PKillGetReq(thePBPtr,async); æRI PKillGetReq function V-518 æC »Aborting ATP GetRequests ATP GetRequests can now be aborted through the PKillGetReq call. This call looks and works just like the PKillSendReq call, and is used to abort a specific GetRequest call. Previously it was necessary to close the socket to abort all GetRequest calls on the socket. FUNCTION PKillGetReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; Parameter block --> 26 csCode word Always PKillGetReq --> 44 aKillQEl pointer Pointer to queue element PKillGetReq will abort a specific outstanding GetRequest call (as opposed to closing the socket, which aborts all outstanding GetRequests on that socket). The call will be completed with a reqAborted error. To abort a GetRequest, place a pointer to the queue element of the call to abort in aKillQEl and issue the PKillGetReq call. Result Codes noErr No error cbNotFound aKillQEl does not point to a GetReq queue element æKY PKillNBP æFp Appletalk.p æT FUNCTION æD FUNCTION PKillNBP(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PKillNBP(thePBptr,async); æRI PKillNBP function V-518 æC _______________________________________________________________________________ »NAME BINDING PROTOCOL CHANGES _______________________________________________________________________________ Changes to the Name Binding Protocol include supporting multiple concurrent requests and a means for aborting an active request. »Multiple Concurrent NBP Requests NBP now supports multiple concurrent active requests. Specifically, a number of LookupNames, RegisterNames and ConfirmNames can all be active concurrently. The maximum number of concurrent requests is machine dependent; if it is exceeded the error tooManyReqs will be returned. Active requests can be aborted by the PKillNBP call. »KillNBP function FUNCTION PKillNBP (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; •••Refer to Technical Note #199:••• Parameter block --> 26 csCode word Always PKillNBP --> 28 aKillQEl pointer Pointer to queue element PKillNBP is used to abort an outstanding LookupName, RegisterName or ConfirmName request. To abort one of these calls, place a pointer to the queue element of the call to abort in a KillQEl and issue the PKillNBP call. The call will be completed with a ReqAborted error. Result Codes noErr No error cbNotFound aKillQEl does not point to a valid NBP queue element æKY PKillSendReq æFp Appletalk.p æT FUNCTION æD FUNCTION PKillSendReq(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PKillSendReq(thePBPtr,async); æRI PKillSendReq function V-517 æC »Aborting ATP SendRequests The RelTCB call is still supported, but only for aborting SendRequests. To abort PNSendRequests, a new call, PKillSendReq, has been added. This call will abort both SendRequests and PNSendRequests. PKillSendReq’s only argument is the queue element pointer of the request to be aborted. The queue element pointer is passed at the offset of the PKillSendReq queue element specified by aKillQE1. FUNCTION PKillSendReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr; Parameter block --> 26 csCode word Always PKillSendReq --> 44 aKillQEl pointer Pointer to queue element PKillSendReq is functionally equivalent to RelTCB, except that it takes different arguments and will abort both SendRequests and PNSendRequests. To abort one of these calls, place a pointer to the queue element of the call to abort in aKillQEl and issue the PKillSendReq call. Result Codes noErr No error cbNotFound aKillQEl does not point to a SendReq or NSendReq queue element æKY PLookupName æFp Appletalk.p æT FUNCTION æD FUNCTION PLookupName(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PLookupName(thePBptr,async); æRI LookupName function II-323,V-513 æC LookupName function Parameter block -> 26 csCode word ;always lookupName -> 28 interval byte ;retry interval <-> 29 count byte ;retry count -> 30 entityPtr pointer ;pointer to entity name -> 34 retBuffPtr pointer ;pointer to buffer -> 38 retBuffSize word ;buffer size in bytes -> 40 maxToGet word ;matches to get <-> 42 numGotten word ;matches found LookupName returns the addresses of all entities with a specified name. EntityPtr points to the entity's name (in the form shown in Figure 13 above). Meta- characters are allowed in the entity name. RetBuffPtr and retBuffSize contain the location and size of an area of memory in which the tuples describing the entity names and their corresponding addresses should be returned. MaxToGet indicates the maximum number of matching names to find addresses for; the actual number of addresses found is returned in numGotten. Interval and count contain the retry interval and the retry count. LookupName completes when either the number of matches is equal to or greater than maxToGet, or the retry count has been exceeded. The count field is decremented for each retransmission. Note: NumGotten is first set to 0 and then incremented with each match found. You can test the value in this field, and can start examining the received addresses in the buffer while the lookup continues. Result codes noErr No error nbpBuffOvr Buffer overflow æKY PNSendRequest æFp Appletalk.p æT FUNCTION æD FUNCTION PNSendRequest(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PNSendRequest(thePBPtr,async); æRI PNSendRequest function V-516 æC »Sending an ATP Request Through a Specified Socket ATP requests can now be sent through client-specified sockets. ATP previously would open a dynamic socket, send the request through it, and close the socket when the request was completed. The client can now choose to send a request through an already-opened socket; this also allows more than one request to be sent per socket. A new call, PNSendRequest, has been added for this purpose. The function of the old SendRequest call itself remains unchanged. FUNCTION PNSendRequest (thePBptr: ATPBPtr; async: BOOLEAN) : OSErr; Parameter block --> 18 userData longword User bytes <-- 22 reqTID word Transaction ID used in request --> 26 csCode word Always sendRequest <-> 28 atpSocket byte Socket to send request on or current bitmap <-> 29 atpFlags byte Control information --> 30 addrBlock longword Destination socket address --> 34 reqLength word Request size in bytes --> 36 reqPointer pointer Pointer to request data --> 40 bdsPointer pointer Pointer to response BDS --> 44 numOfBuffs byte Number of responses expected --> 45 timeOutVal byte Timeout interval <-- 46 numOf Resps byte Number of responses received <-> 47 retryCount byte Number of retries <-- 48 intBuff word Used internally The PNSendRequest call is functionally equivalent to the SendRequest call, however PNSendRequest allows you to specify, in the atpSocket field, the socket through which the request is to be sent. This socket must have been previously opened through an OpenATPSkt request (otherwise a badATPSkt error will be returned). Note that PNSendRequest requires two additional bytes of memory at the end of the parameter block, immediately following the retryCount. These bytes are for the internal use of the AppleTalk Manager and should not be modified while the PNSendRequest call is active. There is a machine-dependent limit as to the number of concurrent PNSendRequests that can be active on a given socket. If this limit is exceeded, the error tooManyReqs is returned. One additional difference between SendRequest and PNSendRequest is that a PNSendRequest can only be aborted by a PKillSendReq call (see below), whereas a SendRequest can be aborted by either a RelTCB or KillSendReq call. Result Codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests noDataArea Too many outstanding ATP calls reqAborted Request cancelled by user æKY POpenATPSkt æFp Appletalk.p æT FUNCTION æD FUNCTION POpenATPSkt(thePBptr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := POpenATPSkt(thePBptr,async); æRI OpenATPSkt function II-315,V-513 æC OpenATPSkt function Parameter block -> 26 csCode word ;always openATPSkt <-> 28 atpSocket byte ;socket number -> 30 addrBlock long word ;socket request specification OpenATPSkt opens a socket for the purpose of receiving requests. ATPSocket contains the socket number of the socket to open. If it's 0, a number is dynamically assigned and returned in atpSocket. AddrBlock contains a specification of the socket addresses from which requests will be accepted. A 0 in the network number, node ID, or socket number field of addrBlock means that requests will be accepted from every network, node, or socket, respectively. Result codes noErr No error tooManySkts Too many responding sockets noDataArea Too many outstanding ATP calls æKY POpenSkt æFp Appletalk.p æT FUNCTION æD FUNCTION POpenSkt(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := POpenSkt(thePBptr,async); æRI OpenSkt function II-311, V-513 æC OpenSkt function Parameter block -> 26 csCode word ;always openSkt <-> 28 socket byte ;socket number -> 30 listener pointer ;socket listener OpenSkt adds a socket and its socket listener to the socket table. If the socket parameter is nonzero, it must be in the range 64 to 127, and it specifies the socket's number; if socket is 0, OpenSkt opens a socket with a socket number in the range 128 to 254, and returns it in the socket parameter. Listener contains a pointer to the socket listener. OpenSkt will return ddpSktErr if you pass the number of an already opened socket, if you pass a socket number greater than 127, or if the socket table is full (the socket table can hold a maximum of 12 sockets). Result codes noErr No error ddpSktErr Socket error æKY PRegisterName æFp Appletalk.p æT FUNCTION æD FUNCTION PRegisterName(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PRegisterName(thePBptr,async); æRI RegisterName function II-322,V-513 æC RegisterName function Parameter block -> 26 csCode word ;always registerName -> 28 interval byte ;retry interval <-> 29 count byte ;retry count -> 30 ntQElPtr pointer ;names table element pointer -> 34 verifyFlag byte ;set if verify needed RegisterName adds the name and address of an entity to the node's names table. NTQElPtr points to a names table entry containing the entity's name and internet address (in the form shown in Figure 13 above). Meta-characters aren't allowed in the object and type fields of the entity name; the zone field, however, must contain the meta-character "*". If verifyFlag is TRUE, RegisterName checks on the network to see if the name is already in use, and returns a result code of nbpDuplicate if so. Interval and count contain the retry interval in eight-tick units and the retry count. When a retry is made, the count field is modified. Warning: The names table entry passed to RegisterName remains the property of NBP until removed from the names table. Don't attempt to remove or modify it. If you've allocated memory using a NewHandle call, you must lock it as long as the name is registered. Warning: VerifyFlag should normally be set before calling RegisterName. Result codes noErr No error nbpDuplicate Duplicate name already exists nbpNISErr Error opening names information socket æKY PRelRspCB æFp Appletalk.p æT FUNCTION æD FUNCTION PRelRspCB(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PRelRspCB(thePBPtr,async); æRI RelRspCB function II-319,V-514 æC RelRspCB function Parameter block -> 26 csCode word ;always relRspCB -> 28 atpSocket byte ;socket number that request was received on -> 30 addrBlock long word ;source of request -> 46 transID word ;transaction ID of request In an exactly-once transaction, RelRspCB cancels the specified SendResponse, without waiting for the release timer to expire or a TRel packet to be received. No error is returned for the SendResponse call. Whan called to cancel a transaction that isn't using exactly-once service, RelRspCB returns cbNotFound. The transaction ID can be obtained from the reqTID field of the SendResponse queue entry; see the description of SendResponse for details. Result codes noErr No error cbNotFound ATP control block not found æKY PRelTCB æFp Appletalk.p æT FUNCTION æD FUNCTION PRelTCB(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PRelTCB(thePBPtr,async); æRI RelTCB function II-319,V-513 æC RelTCB function Parameter block -> 26 csCode word ;always relTCB -> 30 addrBlock long word ;destination of request -> 46 transID word ;transaction ID of request RelTCB dequeues the specified SendRequest call and returns the result code reqAborted for the aborted call. The transaction ID can be obtained from the reqTID field of the SendRequest queue entry; see the description of SendRequest for details. Result codes noErr No error cbNotFound ATP control block not found noDataArea Too many outstanding ATP calls æKY PRemoveName æFp Appletalk.p æT FUNCTION æD FUNCTION PRemoveName(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PRemoveName(thePBptr,async); æRI RemoveName function II-324,V-513 æC RemoveName function Parameter block -> 26 csCode word ;always removeName -> 30 entityPtr pointer ;pointer to entity name RemoveName removes an entity name from the names table of the given entity's node. Result codes noErr No error nbpNotFound Name not found æKY PSendRequest æFp Appletalk.p æT FUNCTION æD FUNCTION PSendRequest(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PSendRequest(thePBPtr,async); æRI SendRequest function II-316,V-513 æC SendRequest function Parameter block -> 18 userData long word ;user bytes <- 22 reqTID word ;transaction ID used in request -> 26 csCode word ;always sendRequest <- 28 currBitMap byte ;bit map <-> 29 atpFlags byte ;control information -> 30 addrBlock long word ;destination socket address -> 34 reqLength word ;request size in bytes -> 36 reqPointer pointer ;pointer to request data -> 40 bdsPointer pointer ;pointer to response BDS -> 44 numOfBuffs byte ;number of responses expected -> 45 timeOutVal byte ;timeout interval <- 46 numOfResps byte ;number of responses received <-> 47 retryCount byte ;number of retries SendRequest sends a request to another socket and waits for a response. UserData contains the four user bytes. AddrBlock indicates the socket to which the request should be sent. ReqLength and reqPointer contain the size and location of the request to send. BDSPointer points to a response BDS where the responses are to be returned; numOfBuffs indicates the number of responses requested. The number of responses received is returned in numOfResps. If a nonzero value is returned in numOfResps, you can examine currBitMap to determine which packets of the transaction were actually received and to detect pieces for higher-level recovery, if desired. TimeOutVal indicates the number of seconds that SendRequest should wait for a response before resending the request. RetryCount indicates the maximum number of retries SendRequest should attempt. The end-of-message flag of atpFlags will be set if the EOM bit is set in the last packet received in a valid response sequence. The exactly-once flag should be set if you want the request to be part of an exactly-once transaction. To cancel a SendRequest call, you need the transaction ID; it's returned in reqTID. You can examine reqTID before the completion of the call, but its contents are valid only after the tidValid bit of atpFlags has been set. SendRequest completes when either an entire response is received or the retry count is exceeded. Note: The value provided in retryCount will be modified during SendRequest if any retries are made. This field is used to monitor the number of retries; for each retry, it's decremented by 1. Result codes noErr No error reqFailed Retry count exceeded tooManyReqs Too many concurrent requests noDataArea Too many outstanding ATP calls reqAborted Request canceled by user æKY PSendResponse æFp Appletalk.p æT FUNCTION æD FUNCTION PSendResponse(thePBPtr: ATPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PSendResponse(thePBPtr,async); æRI SendResponse function II-317,V-513 æC SendResponse function Parameter block <- 18 userData long word ;user bytes from TRel <- 22 reqTID word ;transaction ID used in request -> 26 csCode word ;always sendResponse -> 28 atpSocket byte ;socket number -> 29 atpFlags byte ;control information -> 30 addrBlock long word ;response destination -> 40 bdsPointer pointer ;pointer to response BDS -> 44 numOfBuffs byte ;number of response packets being sent -> 45 bdsSize byte ;BDS size in elements -> 46 transID word ;transaction ID SendResponse sends a response to a socket. If the response was part of an exactly- once transaction, userData will contain the user bytes from the TRel packet. ATPSocket contains the socket number from which the response should be sent. The end-of-message flag in atpFlags should be set if the response contains the final packet in a transaction composed of a group of packets and the number of responses is less than requested. AddrBlock indicates the address of the socket to which the response should be sent. BDSPointer points to a response BDS containing room for the maximum number of responses to be sent; bdsSize contains this maximum number. NumOfBuffs contains the number of response packets to be sent in this call; you may wish to make AddResponse calls to complete the response. TransID indicates the transaction ID of the associated request. During exactly-once transactions, SendResponse doesn't complete until either a TRel packet is received from the socket that made the request, or the retry count is exceeded. Result codes noErr No error badATPSkt Bad responding socket noRelErr No release received noDataArea Too many outstanding ATP calls badBuffNum Sequence number out of range æKY PSetSelfSend æFp Appletalk.p æT FUNCTION æD FUNCTION PSetSelfSend(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PSetSelfSend(thePBptr,async); æRI PSetSelfSend function V-516 æC _______________________________________________________________________________ »SENDING PACKETS TO ONE’S OWN NODE _______________________________________________________________________________ Upon opening, the ability to send a packet to one’s own node (intranode delivery) is disabled. This feature of the AppleTalk Manager can be manipulated through the SetSelfSend function. Once enabled, it is possible, at all levels, to send packets to entities within one’s own node. An example of where this might be desirable is an application sending data to a print spooler that is actually running in the background on the same node. Enabling (or disabling) this feature affects the entire node and should be performed with care. For instance, a desk accessory may not expect to receive names from within its own node as a response to an NBP look-up; enabling this feature from an application could break the desk accessory. All future programs should be written with this feature in mind. FUNCTION PSetSelfSend (thePBptr: MPPPBPtr; async: BOOLEAN) : OSErr; Parameter Block --> 26 csCode word Always PSetSelfSend --> 28 newSelfFlag byte New SelfSend flag <-- 29 oldSelfFlag byte Old SelfSend flag PSetSelfSend enables or disables the intranode delivery feature of the AppleTalk Manager. If newSelfFlag is nonzero, the feature will be enabled; otherwise it will be disabled. The previous value of the flag will be returned in oldSelfFlag. Result Codes noErr No error æKY PWriteDDP æFp Appletalk.p æT FUNCTION æD FUNCTION PWriteDDP(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PWriteDDP(thePBptr,async); æRI WriteDDP function II-312,V-513 æC WriteDDP function Parameter block -> 26 csCode word ;always writeDDP -> 28 socket byte ;socket number -> 29 checksumFlag byte ;checksum flag -> 30 wdsPointer pointer ;write data structure WriteDDP sends a datagram to another socket. WDSPointer points to a write data structure containing the datagram and the address of the destination socket. If checksumFlag is TRUE, WriteDDP will compute the checksum for all datagrams requiring long headers. Result codes noErr No error ddpLenErr Datagram length too big ddpSktErr Socket error noBridgeErr No bridge found æKY PWriteLAP æFp Appletalk.p æT FUNCTION æD FUNCTION PWriteLAP(thePBptr: MPPPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PWriteLAP(thePBptr,async); æRI WriteLAP function II-307, V-513 æC WriteLAP function Parameter block -> 26 csCode word ;always writeLAP -> 30 wdsPointer pointer ;write data structure WriteLAP sends a frame to another node. The frame data and destination of the frame are described by the write data structure pointed to by wdsPointer. The first two data bytes of an ALAP frame sent to another computer using the AppleTalk Manager must indicate the length of the frame in bytes. The ALAP protocol type byte must be in the range 1 to 127. Result codes noErr No error excessCollsns No CTS received after 32 RTS's ddpLengthErr Packet length exceeds maximum lapProtErr Invalid ALAP protocol type æKY RemoveHdlBlocks æFp Appletalk.p æT PROCEDURE æD PROCEDURE RemoveHdlBlocks; æDT RemoveHdlBlocks; æKY RetransType æFp AppleTalk.p æT PACKED RECORD æC RetransType = PACKED RECORD retransInterval: Byte; retransCount: Byte; END; æKY scbMemSize æFp Appletalk.p æC scbMemSize = 192; {Size of memory for SCB } æKY Str32 æFp AppleTalk.p æT TYPE æC Str32 = String[32]; æKY WDSElement æFp AppleTalk.p æT RECORD æC WDSElement = RECORD entryLength: INTEGER; entryPtr: Ptr; END; æKY xppFlagClr æFp Appletalk.p æC xppFlagClr = 0; {Cs for AFPCommandBlock } æKY xppFlagSet æFp Appletalk.p æC xppFlagSet = 128; {StartEndFlag & NewLineFlag fields. } æKY xppLoadedBit æFp Appletalk.p æC xppLoadedBit = 5; { XPP bit in PortBUse } æKY xppRefNum æFp Appletalk.p æC xppRefNum = -41; {.XPP reference number } æKY xppUnitNum æFp Appletalk.p æC xppUnitNum = 40; {Unit number for XPP (old ROMs) } æKY Controls.p æKL DisposeControl DragControl Draw1Control DrawControls FindControl GetAuxCtl GetCRefCon GetCTitle GetCtlAction GetCtlMax GetCtlMin GetCtlValue GetCVariant GetNewControl HideControl HiliteControl KillControls MoveControl NewControl SetCRefCon SetCTitle SetCtlAction SetCtlColor SetCtlMax SetCtlMin SetCtlValue ShowControl SizeControl TestControl TrackControl UpdtControl autoTrack AuxCtlHandle AuxCtlPtr AuxCtlRec calcCRgns cBodyColor CColorTable CCTabHandle CCTabPtr cFrameColor checkBoxProc ColorTable ControlHandle ControlPtr ControlRecord CTabHandle CTabPtr cTextColor cThumbColor dispCntl dragCntl drawCntl hAxisOnly inButton inCheckBox inDownButton initCntl inPageDown inPageUp inThumb inUpButton noConstraint posCntl pushButProc radioButProc scrollBarProc testCntl thumbCntl useWFont vAxisOnly æKY AuxCtlRec,AuxCtlPtr,AuxCtlHandle æFp Controls.p æT TYPE æC AuxCtlPtr = ^AuxCtlRec; AuxCtlHandle = ^AuxCtlPtr; AuxCtlRec = RECORD acNext: AuxCtlHandle; {handle to next AuxCtlRec} acOwner: ControlHandle; {handle for aux record's control} acCTable: CCTabHandle; {color table for this control} acFlags: INTEGER; {misc flag byte} acReserved: LONGINT; {reserved for use by Apple} acRefCon: LONGINT; {for use by application} END; The information needed for drawing controls in color is kept in a linked list of auxiliary control records, beginning in the global variable AuxCtlHead. (Notice that there is just one global list for all controls in all windows, not a separate one for each window.) Each window record has a handle to the list of controls. Figure 5 shows the auxiliary control list structure. •••Refer to Figure 5.••• Figure 5–Auxiliary Control List Each auxiliary control record is a relocatable object residing in the application heap. The most important information it holds is a handle to the control’s individual color table (see the “Control Color Tables” section). The rest of the record consists of a link to the next record in the list, a field that identifies the control’s owner, a 4-byte field reserved for future expansion, and a 4-byte reference constant for use by the application: TYPE AuxCtlHandle = ^AuxCtlPtr; AuxCtlPtr = ^AuxCtlRec; AuxCtlRec = RECORD acNext: AuxCtlHandle; {handle to next record in list} acOwner: ControlHandle; {handle to owning control} acCTable: CCTabHandle; {handle to control's color } { table} acFlags: INTEGER; {miscellaneous flags; reserved} acReserved: LONGINT; {reserved for future expansion} acRefCon: LONGINT {reserved for application use} END; Field descriptions acNext The acNext field contains a handle to the next record in the auxiliary control list. acOwner The acOwner field contains the handle of the control to which this auxiliary record belongs. Used as an ID field. acCTable The acCTable contains the handle to the control’s color table (see “Control Color Tables” below). acFlags The acFlags field contains miscellaneous flags for use by the Control Manager; this field is reserved. acReserved The acReserved field is reserved for future expansion; this must be set to 0 for future compatibility. acRefCon The acRefCon field is a reference constant for use by the application. Not every control needs an auxiliary control record. When an application is started, a resource containing a default color table is loaded from the system resource file; this resource defines a standard set of control colors. Since there is no InitControls routine, this happens when an application calls InitWindows. Separate auxiliary control records are needed only for controls whose color usage differs from the default. Each such nonstandard control must have its own auxiliary record, even if it uses the same colors as another control. This allows two or more auxiliary records to share the same control color table. If the control color table is a resource, it won’t be deleted by DisposeControl. When using an auxiliary record that is not stored as a resource, the application should not deallocate the color table if another control is still using it. A control created from scratch will initially have no auxiliary control record. If it is to use nonstandard colors, it must be given an auxiliary record and a color table with SetCtlColor (see the “Control Manager Routines” section). Such a control should normally be made invisible at creation and then displayed with ShowControl after the colors are set. For controls created from a 'CNTL' resource, the color table can be specified as a resource as well. See the section titled “The Control Color Table Resource”. A/UX systems: When using 32-bit mode. every control has its own auxiliary record. If there is no specific set of control colors for this control, the acCTable will point to the default color table. æKY cFrameColor,cBodyColor,cTextColor,cThumbColor æFp Controls.p æC { Control part colors } cFrameColor = 0; cBodyColor = 1; cTextColor = 2; cThumbColor = 3; æKY ControlRecord,ControlPtr,ControlHandle æFp Controls.p æT TYPE æC ControlPtr = ^ControlRecord; ControlHandle = ^ControlPtr; ControlRecord = PACKED RECORD nextControl: ControlHandle; contrlOwner: WindowPtr; contrlRect: Rect; contrlVis: Byte; contrlHilite: Byte; contrlValue: INTEGER; contrlMin: INTEGER; contrlMax: INTEGER; contrlDefProc: Handle; contrlData: Handle; contrlAction: ProcPtr; contrlRfCon: LONGINT; contrlTitle: Str255; END; Every control is represented internally by a control record containing all pertinent information about that control. The control record contains the following: • A pointer to the window the control belongs to. • A handle to the next control in the window’s control list. • A handle to the control definition function. • The control’s title, if any. • A rectangle that completely encloses the control, which determines the control’s size and location within its window. The entire control, including the title of a check box or radio button, is drawn inside this rectangle. • An indication of whether the control is currently active and how it’s to be highlighted. • The current setting of the control (if this type of control retains a setting) and the minimum and maximum values the setting can assume. For check boxes and radio buttons, a setting of 0 means the control is off and 1 means it’s on. The control record also contains an indication of whether the control is currently visible or invisible. These terms refer only to whether the control is drawn in its window, not to whether you can see it on the screen. A control may be “visible” and still not appear on the screen, because it’s obscured by overlapping windows or other objects. There’s a field in the control record for a pointer to the control’s default action procedure. An action procedure defines some action to be performed repeatedly for as long as the user holds down the mouse button inside the control. The default action procedure may be used by the Control Manager function TrackControl if you call it without passing a pointer to an action procedure; this is discussed in detail in the description of TrackControl in the “Control Manager Routines” section. Finally, the control record includes a 32-bit reference value field, which is reserved for use by your application. You specify an initial reference value when you create a control, and can then read or change the reference value whenever you wish. The data type for a control record is called ControlRecord. A control record is referred to by a handle: TYPE ControlPtr = ^ControlRecord; ControlHandle = ^ControlPtr; The Control Manager functions for creating a control return a handle to a newly allocated control record; thereafter, your program should normally refer to the control by this handle. Most of the Control Manager routines expect a control handle as their first parameter. You can store into and access most of a control record’s fields with Control Manager routines, so normally you don’t have to know the exact field names. However, if you want more information about the exact structure of a control record—if you’re defining your own control types, for instance—it’s given below. _______________________________________________________________________________ »The ControlRecord Data Type The ControlRecord data type is defined as follows: TYPE ControlRecord = PACKED RECORD nextControl: ControlHandle; {next control} contrlOwner: WindowPtr; {control's window} contrlRect: Rect; {enclosing rectangle} contrlVis: Byte; {255 if visible} contrlHilite: Byte; {highlight state} contrlValue: INTEGER; {control's current setting} contrlMin: INTEGER; {control's minimum setting} contrlMax: INTEGER; {control's maximum setting} contrlDefProc: Handle; {control definition function} contrlData: Handle; {data used by contrlDefProc} contrlAction: ProcPtr; {default action procedure} contrlRfCon: LONGINT; {control's reference value} contrlTitle: Str255 {control's title} END; NextControl is a handle to the next control associated with this control’s window. All the controls belonging to a given window are kept in a linked list, beginning in the controlList field of the window record and chained together through the nextControl fields of the individual control records. The end of the list is marked by a NIL value; as new controls are created, they’re added to the beginning of the list. ContrlOwner is a pointer to the window that this control belongs to. ContrlRect is the rectangle that completely encloses the control, in the local coordinates of the control’s window. When contrlVis is 0, the control is currently invisible; when it’s 255, the control is visible. ContrlHilite specifies whether and how the control is to be highlighted, indicating whether it’s active or inactive. The HiliteControl procedure lets you set this field; see the description of HiliteControl for more information about the meaning of the field’s value. ContrlValue is the control’s current setting. For check boxes and radio buttons, 0 means the control is off and 1 means it’s on. For dials, the fields contrlMin and contrlMax define the range of possible settings; contrlValue may take on any value within that range. Other (custom) control types can use these three fields as they see fit. ContrlDefProc is a handle to the control definition function for this type of control. When you create a control, you identify its type with a control definition ID, which is converted into a handle to the control definition function and stored in the contrlDefProc field. Thereafter, the Control Manager uses this handle to access the definition function; you should never need to refer to this field directly. Note: When not running in 32-bit mode, the high-order byte of the contrlDefProc field contains some additional information that the Control Manager gets from the control definition ID; for details, see the section “Defining Your Own Controls”. ContrlData is reserved for use by the control definition function, typically to hold additional information specific to a particular control type. For example, the standard definition function for scroll bars uses this field for a handle to the region containing the scroll bar’s thumb. If no more than four bytes of additional information are needed, the definition function can store the information directly in the contrlData field rather than use a handle. ContrlAction is a pointer to the control’s default action procedure, if any. The Control Manager function TrackControl may call this procedure to respond to the user’s dragging the mouse inside the control. ContrlRfCon is the control’s reference value field, which the application may store into and access for any purpose. ContrlTitle is the control’s title, if any. æKY DisposeControl æFp Controls.p æT PROCEDURE æTN $A955 æD PROCEDURE DisposeControl(theControl: ControlHandle); æDT DisposeControl(theControl); æMM æRI DisposeControl procedure I-321, P-168 æC Assembly-language note: The macro you invoke to call DisposeControl from assembly language is named _DisposControl. DisposeControl removes theControl from the screen, deletes it from its window’s control list, and releases the memory occupied by the control record and any data structures associated with the control. æKY DragControl æFp Controls.p æT PROCEDURE æTN $A967 æD PROCEDURE DragControl(theControl: ControlHandle;startPt: Point;limitRect: Rect; slopRect: Rect;axis: INTEGER); æDT DragControl(theControl,startPt,limitRect,slopRect,axis); æMM æRI DragControl procedure I-325 æC Called with the mouse button down inside theControl, DragControl pulls a dotted outline of the control around the screen, following the movements of the mouse until the button is released. When the mouse button is released, DragControl calls MoveControl to move the control to the location to which it was dragged. Note: Before beginning to follow the mouse, DragControl calls the control definition function to allow it to do its own “custom dragging” if it chooses. If the definition function doesn’t choose to do any custom dragging, DragControl uses the default method of dragging described here. The startPt, limitRect, slopRect, and axis parameters have the same meaning as for the Window Manager function DragGrayRgn. These parameters are reviewed briefly below; see the description of DragGrayRgn in the Window Manager chapter for more details. • StartPt is assumed to be the point where the mouse button was originally pressed, in the local coordinates of the control’s window. • LimitRect limits the travel of the control’s outline, and should normally coincide with or be contained within the window’s content region. • SlopRect allows the user some “slop” in moving the mouse; it should completely enclose limitRect. • The axis parameter allows you to constrain the control’s motion to only one axis. It has one of the following values: CONST noConstraint = 0; {no constraint} hAxisOnly = 1; {horizontal axis only} vAxisOnly = 2; {vertical axis only} Assembly-language note: Like TrackControl, DragControl invokes the macro _DragTheRgn, so you can use the global variables DragHook and DragPattern. æKY Draw1Control æFp Controls.p æT PROCEDURE æTN $A96D æD PROCEDURE Draw1Control(theControl: ControlHandle); æDT Draw1Control(theControl); æMM æRI Draw1Control procedure IV-53 æC [128K ROM] Draw1Control draws the specified control if it’s visible within the window. æKY drawCntl,testCntl,calcCRgns,initCntl,dispCntl,posCntl,thumbCntl,dragCntl,autoTrack æFp Controls.p æC { Messages to control definition function } drawCntl = 0; {draw the control (or control part)} testCntl = 1; {test where mouse button was pressed} calcCRgns = 2; {calculate control's region (or indicator's)} initCntl = 3; {do any additional control initialization} dispCntl = 4; {take any additional disposal actions} posCntl = 5; {reposition control's indicator and update it} thumbCntl = 6; {calculate parameters for dragging indicator} dragCntl = 7; {drag control (or its indicator)} autoTrack = 8; {execute control's action procedure} æKY DrawControls æFp Controls.p æT PROCEDURE æTN $A969 æD PROCEDURE DrawControls(theWindow: WindowPtr); æDT DrawControls(theWindow); æRT 203 æRI DrawControls procedure I-322, P-169 æC DrawControls draws all controls currently visible in theWindow. The controls are drawn in reverse order of creation; thus in case of overlap the earliest-created controls appear frontmost in the window. Note: Window Manager routines such as SelectWindow, ShowWindow, and BringToFront do not automatically call DrawControls to display the window’s controls. They just add the appropriate regions to the window’s update region, generating an update event. Your program should always call DrawControls explicitly upon receiving an update event for a window that contains controls. æKY FindControl æFp Controls.p æT FUNCTION æTN $A96C æD FUNCTION FindControl(thePoint: Point;theWindow: WindowPtr;VAR theControl: ControlHandle): INTEGER; æDT myVariable := FindControl(thePoint,theWindow,theControl); æMM æRI FindControl function I-323, P-98, 114, 170 æC When the Window Manager function FindWindow reports that the mouse button was pressed in the content region of a window, and the window contains controls, the application should call FindControl with theWindow equal to the window pointer and thePoint equal to the point where the mouse button was pressed (in the window’s local coordinates). FindControl tells which of the window’s controls, if any, the mouse button was pressed in: • If it was pressed in a visible, active control, FindControl sets the whichControl parameter to the control handle and returns a part code identifying the part of the control that it was pressed in. • If it was pressed in an invisible or inactive control, or not in any control, FindControl sets whichControl to NIL and returns 0 as its result. Warning: Notice that FindControl expects the mouse point in the window’s local coordinates, whereas FindWindow expects it in global coordinates. Always be sure to convert the point to local coordinates with the QuickDraw procedure GlobalToLocal before calling FindControl. Note: FindControl also returns NIL for whichControl and 0 as its result if the window is invisible or doesn’t contain the given point. In these cases, however, FindWindow wouldn’t have returned this window in the first place, so the situation should never arise. æKY GetAuxCtl æFp Controls.p æT FUNCTION æTN $AA44 æD FUNCTION GetAuxCtl(theControl: ControlHandle;VAR acHndl: AuxCtlHndl): BOOLEAN; æDT myVariable := GetAuxCtl(theControl,acHndl); æMM æRI GetAuxCtl function V-222 æC [Macintosh II] The GetAuxCtl function returns a handle to a control’s AuxCtlRec: • If the given control has its own color table, the function returns TRUE. • If the control used the default color set, the function returns FALSE. • If the control asked to receive the default color set (theControl = NIL), then the function returns TRUE. æKY GetCRefCon æFp Controls.p æT FUNCTION æTN $A95A æD FUNCTION GetCRefCon(theControl: ControlHandle): LONGINT; æDT myVariable := GetCRefCon(theControl); æRI GetCRefCon function I-327 æC GetCRefCon returns theControl’s current reference value. æKY GetCTitle æFp Controls.p æT PROCEDURE æTN $A95E æD PROCEDURE GetCTitle(theControl: ControlHandle;VAR title: Str255); æDT GetCTitle(theControl,title); æRI GetCTitle procedure I-321 æC GetCTitle returns theControl’s title as the value of the title parameter. æKY GetCtlAction æFp Controls.p æT FUNCTION æTN $A96A æD FUNCTION GetCtlAction(theControl: ControlHandle): ProcPtr; æDT myVariable := GetCtlAction(theControl); æRI GetCtlAction function I-328, IV-53 æC GetCtlAction returns a pointer to theControl’s default action procedure, if any. (It returns whatever is in that field of the control record.) æKY GetCtlMax æFp Controls.p æT FUNCTION æTN $A962 æD FUNCTION GetCtlMax(theControl: ControlHandle): INTEGER; æDT myVariable := GetCtlMax(theControl); æRI GetCtlMax function I-327 æC Assembly-language note: The macro you invoke to call GetCtlMax from assembly language is named _GetMaxCtl. GetCtlMax returns theControl’s maximum setting. æKY GetCtlMin æFp Controls.p æT FUNCTION æTN $A961 æD FUNCTION GetCtlMin(theControl: ControlHandle): INTEGER; æDT myVariable := GetCtlMin(theControl); æRI GetCtlMin function I-327 æC Assembly-language note: The macro you invoke to call GetCtlMin from assembly language is named _GetMinCtl. GetCtlMin returns theControl’s minimum setting. æKY GetCtlValue æFp Controls.p æT FUNCTION æTN $A960 æD FUNCTION GetCtlValue(theControl: ControlHandle): INTEGER; æDT myVariable := GetCtlValue(theControl); æRI GetCtlValue function I-326, P-114, 171 æC GetCtlValue returns theControl’s current setting. æKY GetCVariant æFp Controls.p æT FUNCTION æTN $A809 æD FUNCTION GetCVariant(theControl: ControlHandle): INTEGER; æDT myVariable := GetCVariant(theControl); æRI GetCVariant function V-222 æC [Macintosh Plus, Macintosh SE, and Macintosh II] The GetVariant function returns the variant control value for the control described by theControl. This value was formerly stored in the high four bits of the control defproc handle; for future compatibility, use the GetCVariant routine to access this value. æKY GetNewControl æFp Controls.p æT FUNCTION æTN $A9BE æD FUNCTION GetNewControl(controlID: INTEGER;owner: WindowPtr): ControlHandle; æDT myVariable := GetNewControl(controlID,owner); æMM æRT 203 æRI GetNewControl function I-321, P-112, 113, 114, 172 æC GetNewControl creates a control from a control template stored in a resource file, adds it to the beginning of theWindow’s control list, and returns a handle to the new control. ControlID is the resource ID of the template. GetNewControl works exactly the same as NewControl (above), except that it gets the initial values for the new control’s fields from the specified control template instead of accepting them as parameters. If the control template can’t be read from the resource file, GetNewControl returns NIL. It releases the memory occupied by the resource before returning. The system default control colors are stored in the System file and ROMResources as 'cctb' resource = 0. By including a 'cctb' resource = 0 in your application, it is possible to change the default colors that will be used for all controls, unless a specific 'cctb' exists for a control defined within the application. When you use GetNewControl for the control resource 'CNTL', GetNewControl will attempt to load a 'cctb' resource with the same ID as the 'CNTL' resource ID, if one is present. It then executes the SetCtlColor call. The following part identifiers for control elements should be present in the ColorSpec.value field: cFrameColor (0) Frame color cBodyColor (1) Fill color for body of control cTextColor (2) Text color cThumbColor (3) Thumb color These identifiers may be present in any order; for instance, the text or indicator color values may be stored before the fill and frame colors in the ColorSpec record structure. If a part identifier is not found, then the first color in the color table will be used. æKY HideControl æFp Controls.p æT PROCEDURE æTN $A958 æD PROCEDURE HideControl(theControl: ControlHandle); æDT HideControl(theControl); æMM æRI HideControl procedure I-322, P-113, 114, 174 æC HideControl makes theControl invisible. It fills the region the control occupies within its window with the background pattern of the window’s grafPort. It also adds the control’s enclosing rectangle to the window’s update region, so that anything else that was previously obscured by the control will reappear on the screen. If the control is already invisible, HideControl has no effect. æKY HiliteControl æFp Controls.p æT PROCEDURE æTN $A95D æD PROCEDURE HiliteControl(theControl: ControlHandle;hiliteState: INTEGER); æDT HiliteControl(theControl,hiliteState); æMM æRI HiliteControl procedure I-322 æC HiliteControl changes the way theControl is highlighted. HiliteState has one of the following values: • The value 0 means no highlighting. (The control is active.) • A value between 1 and 253 is interpreted as a part code designating the part of the (active) control to be highlighted. • The value 255 means that the control is to be made inactive and highlighted accordingly. Note: The value 254 should not be used; this value is reserved for future use. HiliteControl calls the control definition function to redraw the control with its new highlighting. æKY inButton,inCheckBox,inUpButton,inDownButton,inPageUp,inPageDown,inThumb æFp Controls.p æC { Part codes } inButton = 10; {simple button} inCheckBox = 11; {check box or radio button} inUpButton = 20; {up arrow of a scroll bar} inDownButton = 21; {down arrow of a scroll bar} inPageUp = 22; {"page up" region of a scroll bar} inPageDown = 23; {"page down" region of a scroll bar} inThumb = 129; {thumb of a scroll bar} æKY KillControls æFp Controls.p æT PROCEDURE æTN $A956 æD PROCEDURE KillControls(theWindow: WindowPtr); æDT KillControls(theWindow); æMM æRI KillControls procedure I-321, P-113, 175 æC KillControls disposes of all controls associated with theWindow by calling DisposeControl (above) for each. Note: Remember that the Window Manager procedures CloseWindow and DisposeWindow automatically dispose of all controls associated with the given window. æKY MoveControl æFp Controls.p æT PROCEDURE æTN $A959 æD PROCEDURE MoveControl(theControl: ControlHandle;h: INTEGER;v: INTEGER); æDT MoveControl(theControl,h,v); æMM æRI MoveControl procedure I-325, P-113, 176 æC MoveControl moves theControl to a new location within its window. The top left corner of the control’s enclosing rectangle is moved to the horizontal and vertical coordinates h and v (given in the local coordinates of the control’s window); the bottom right corner is adjusted accordingly, to keep the size of the rectangle the same as before. If the control is currently visible, it’s hidden and then redrawn at its new location. æKY NewControl æFp Controls.p æT FUNCTION æTN $A954 æD FUNCTION NewControl(theWindow: WindowPtr;boundsRect: Rect;title: Str255; visible: BOOLEAN;value: INTEGER;min: INTEGER;max: INTEGER;procID: INTEGER; refCon: LONGINT): ControlHandle; æDT myVariable := NewControl(theWindow,boundsRect,title,visible,value,min, max,procID,refCon); æMM æRI NewControl function I-319, P-112, 114, 177 æC NewControl creates a control, adds it to the beginning of theWindow’s control list, and returns a handle to the new control. The values passed as parameters are stored in the corresponding fields of the control record, as described below. The field that determines highlighting is set to 0 (no highlighting) and the pointer to the default action procedure is set to NIL (none). Note: The control definition function may do additional initialization, including changing any of the fields of the control record. The only standard control for which additional initialization is done is the scroll bar; its control definition function allocates space for a region to hold the thumb and stores the region handle in the contrlData field of the control record. TheWindow is the window the new control will belong to. All coordinates pertaining to the control will be interpreted in this window’s local coordinate system. BoundsRect, given in theWindow’s local coordinates, is the rectangle that encloses the control and thus determines its size and location. Note the following about the enclosing rectangle for the standard controls: • Simple buttons are drawn to fit the rectangle exactly. (The control definition function calls the QuickDraw procedure FrameRoundRect.) To allow for the tallest characters in the system font, there should be at least a 20-point difference between the top and bottom coordinates of the rectangle. • For check boxes and radio buttons, there should be at least a 16-point difference between the top and bottom coordinates. • By convention, scroll bars are 16 pixels wide, so there should be a 16-point difference between the left and right (or top and bottom) coordinates. (If there isn’t, the scroll bar will be scaled to fit the rectangle.) A standard scroll bar should be at least 48 pixels long, to allow room for the scroll arrows and thumb. Title is the control’s title, if any (if none, you can just pass the empty string as the title). Be sure the title will fit in the control’s enclosing rectangle; if it won’t it will be truncated on the right for check boxes and radio buttons, or centered and truncated on both ends for simple buttons. Note: Some non-Roman systems write text from right-to-left, in which case radio buttons and check boxes are drawn with their titles on the left of the control. They are also truncated on the left. See the Script Manager chapter for more information. If the visible parameter is TRUE, NewControl draws the control. Note: It does not use the standard window updating mechanism, but instead draws the control immediately in the window. The min and max parameters define the control’s range of possible settings; the value parameter gives the initial setting. For controls that don’t retain a setting, such as buttons, the values you supply for these parameters will be stored in the control record but will never be used. So it doesn’t matter what values you give for those controls—0 for all three parameters will do. For controls that just retain an on-or-off setting, such as check boxes or radio buttons, min should be 0 (meaning the control is off) and max should be 1 (meaning it’s on). For dials, you can specify whatever values are appropriate for min, max, and value. ProcID is the control definition ID, which leads to the control definition function for this type of control. (The function is read into memory if it isn’t already in memory.) The control definition IDs for the standard control types are listed above under “Controls and Resources”. Control definition IDs for custom control types are discussed later under “Defining Your Own Controls”. RefCon is the control’s reference value, set and used only by your application. æKY noConstraint,hAxisOnly,vAxisOnly æFp Controls.p æC { Axis constraints for DragControl } noConstraint = 0; {no constraint} hAxisOnly = 1; {horizontal axis only} vAxisOnly = 2; {vertical axis only} æKY pushButProc,checkBoxProc,radioButProc,useWFont,scrollBarProc æFp Controls.p æC { Control definition IDs } pushButProc = 0; {simple button} checkBoxProc = 1; {check box} radioButProc = 2; {radio button} useWFont = 8; {add to above to use window's font} scrollBarProc = 16; {scroll bar} æKY SetCRefCon æFp Controls.p æT PROCEDURE æTN $A95B æD PROCEDURE SetCRefCon(theControl: ControlHandle;data: LONGINT); æDT SetCRefCon(theControl,data); æRI SetCRefCon procedure I-327 æC SetCRefCon sets theControl’s reference value to the given data. æKY SetCTitle æFp Controls.p æT PROCEDURE æTN $A95F æD PROCEDURE SetCTitle(theControl: ControlHandle;title: Str255); æDT SetCTitle(theControl,title); æMM æRI SetCTitle procedure I-321 æC SetCTitle sets theControl’s title to the given string and redraws the control. æKY SetCtlAction æFp Controls.p æT PROCEDURE æTN $A96B æD PROCEDURE SetCtlAction(theControl: ControlHandle;actionProc: ProcPtr); æDT SetCtlAction(theControl,actionProc); æRI SetCtlAction procedure I-328 æC SetCtlAction sets theControl’s default action procedure to actionProc. æKY SetCtlColor æFp Controls.p æT PROCEDURE æTN $AA43 æD PROCEDURE SetCtlColor(theControl: ControlHandle;newColorTable: CCTabHandle); æDT SetCtlColor(theControl,newColorTable); æMM æRI SetCtlColor procedure V-222 æC [Macintosh II] The SetCtlColor procedure sets or modifies a control’s color table. If the control currently has no auxiliary control record, a new one is created with the given color table and added to the head of the auxiliary control list. If there is already an auxiliary record for the control, its color table is replaced by the contents of newColorTable. If newColorTable has the same contents as the default color table, the control’s existing auxiliary record and color table are removed from the auxiliary control list and deallocated. If theControl = NIL, the operation modifies the default color table itself. If the control is visible, it will be redrawn by SetCtlColor using the new color table. æKY SetCtlMax æFp Controls.p æT PROCEDURE æTN $A965 æD PROCEDURE SetCtlMax(theControl: ControlHandle;maxValue: INTEGER); æDT SetCtlMax(theControl,maxValue); æMM æRI SetCtlMax procedure I-327 æC Assembly-language note: The macro you invoke to call SetCtlMax from assembly language is named _SetMaxCtl. SetCtlMax sets theControl’s maximum setting to maxValue and redraws the control to reflect the new range. If the control’s current setting is greater than maxValue, the setting is changed to the new maximum. Note: If you set the maximum setting of a scroll bar equal to its minimum setting, the control definition function will make the scroll bar inactive. æKY SetCtlMin æFp Controls.p æT PROCEDURE æTN $A964 æD PROCEDURE SetCtlMin(theControl: ControlHandle;minValue: INTEGER); æDT SetCtlMin(theControl,minValue); æMM æRI SetCtlMin procedure I-326 æC Assembly-language note: The macro you invoke to call SetCtlMin from assembly language is named _SetMinCtl. SetCtlMin sets theControl’s minimum setting to minValue and redraws the control to reflect the new range. If the control’s current setting is less than minValue, the setting is changed to the new minimum. æKY SetCtlValue æFp Controls.p æT PROCEDURE æTN $A963 æD PROCEDURE SetCtlValue(theControl: ControlHandle;theValue: INTEGER); æDT SetCtlValue(theControl,theValue); æMM æRT 197 æRI SetCtlValue procedure I-326 æC SetCtlValue sets theControl’s current setting to theValue and redraws the control to reflect the new setting. For check boxes and radio buttons, the value 1 fills the control with the appropriate mark, and 0 clears it. For scroll bars, SetCtlValue redraws the thumb where appropriate. If the specified value is out of range, it’s forced to the nearest endpoint of the current range (that is, if theValue is less than the minimum setting, SetCtlValue sets the current setting to the minimum; if theValue is greater than the maximum setting, it sets the current setting to the maximum). æKY ShowControl æFp Controls.p æT PROCEDURE æTN $A957 æD PROCEDURE ShowControl(theControl: ControlHandle); æDT ShowControl(theControl); æMM æRT 197 æRI ShowControl procedure I-322, P-113, 114, 181 æC ShowControl makes theControl visible. The control is drawn in its window but may be completely or partially obscured by overlapping windows or other objects. If the control is already visible, ShowControl has no effect. æKY SizeControl æFp Controls.p æT PROCEDURE æTN $A95C æD PROCEDURE SizeControl(theControl: ControlHandle;w: INTEGER;h: INTEGER); æDT SizeControl(theControl,w,h); æMM æRI SizeControl procedure I-326, P-113, 181 æC SizeControl changes the size of theControl’s enclosing rectangle. The bottom right corner of the rectangle is adjusted to set the rectangle’s width and height to the number of pixels specified by w and h; the position of the top left corner is not changed. If the control is currently visible, it’s hidden and then redrawn in its new size. æKY TestControl æFp Controls.p æT FUNCTION æTN $A966 æD FUNCTION TestControl(theControl: ControlHandle;thePt: Point): INTEGER; æDT myVariable := TestControl(theControl,thePt); æMM æRI TestControl procedure I-325 æC If theControl is visible and active, TestControl tests which part of the control contains thePoint (in the local coordinates of the control’s window); it returns the corresponding part code, or 0 if the point is outside the control. If the control is invisible or inactive, TestControl returns 0. TestControl is called by FindControl and TrackControl; normally you won’t need to call it yourself. æKY TrackControl æFp Controls.p æT FUNCTION æTN $A968 æD FUNCTION TrackControl(theControl: ControlHandle;thePoint: Point;actionProc: ProcPtr): INTEGER; æDT myVariable := TrackControl(theControl,thePoint,actionProc); æMM æRI TrackControl function I-323, P-114, 184 æC When the mouse button is pressed in a visible, active control, the application should call TrackControl with theControl equal to the control handle and startPt equal to the point where the mouse button was pressed (in the local coordinates of the control’s window). TrackControl follows the movements of the mouse and responds in whatever way is appropriate until the mouse button is released; the exact response depends on the type of control and the part of the control in which the mouse button was pressed. If highlighting is appropriate, TrackControl does the highlighting, and undoes it before returning. When the mouse button is released, TrackControl returns with the part code if the mouse is in the same part of the control that it was originally in, or with 0 if not (in which case the application should do nothing). If the mouse button was pressed in an indicator, TrackControl drags a dotted outline of it to follow the mouse. When the mouse button is released, TrackControl calls the control definition function to reposition the control’s indicator. The control definition function for scroll bars responds by redrawing the thumb, calculating the control’s current setting based on the new relative position of the thumb, and storing the current setting in the control record; for example, if the minimum and maximum settings are 0 and 10, and the thumb is in the middle of the scroll bar, 5 is stored as the current setting. The application must then scroll to the corresponding relative position in the document. TrackControl may take additional actions beyond highlighting the control or dragging the indicator, depending on the value passed in the actionProc parameter, as described below. The following tells you what to pass for the standard control types; for a custom control, what you pass will depend on how the control is defined. • If actionProc is NIL, TrackControl performs no additional actions. This is appropriate for simple buttons, check boxes, radio buttons, and the thumb of a scroll bar. • ActionProc may be a pointer to an action procedure that defines some action to be performed repeatedly for as long as the user holds down the mouse button. (See below for details.) • If actionProc is POINTER(–1), TrackControl looks in the control record for a pointer to the control’s default action procedure. If that field of the control record contains a procedure pointer, TrackControl uses the action procedure it points to; if the field contains POINTER (–1), TrackControl calls the control definition function to perform the necessary action. (If the field contains NIL, TrackControl does nothing.) The action procedure in the control definition function is described in the section “Defining Your Own Controls”. The following paragraphs describe only the action procedure whose pointer is passed in the actionProc parameter or stored in the control record. If the mouse button was pressed in an indicator, the action procedure (if any) should have no parameters. This procedure must allow for the fact that the mouse may not be inside the original control part. If the mouse button was pressed in a control part other than an indicator, the action procedure should be of the form PROCEDURE MyAction (theControl: ControlHandle; partCode: INTEGER); In this case, TrackControl passes the control handle and the part code to the action procedure. (It passes 0 in the partCode parameter if the mouse has moved outside the original control part.) As an example of this type of action procedure, consider what should happen when the mouse button is pressed in a scroll arrow or paging region in a scroll bar. For these cases, your action procedure should examine the part code to determine exactly where the mouse button was pressed, scroll up or down a line or page as appropriate, and call SetCtlValue to change the control’s setting and redraw the thumb. Warning: Since it has a different number of parameters depending on whether the mouse button was pressed in an indicator or elsewhere, the action procedure you pass to TrackControl (or whose pointer you store in the control record) can be set up for only one case or the other. If you store a pointer to a default action procedure in a control record, be sure it will be used only when appropriate for that type of action procedure. The only way to specify actions in response to all mouse-down events in a control, regardless of whether they’re in an indicator, is via the control definition function. Assembly-language note: If you store a pointer to a procedure in the global variable DragHook, that procedure will be called repeatedly (with no parameters) for as long as the user holds down the mouse button. TrackControl invokes the Window Manager macro _DragTheRgn, which calls the DragHook procedure. _DragTheRgn uses the pattern stored in the global variable DragPattern for the dragged outline of the indicator. æKY UpdtControl æFp Controls.p æT PROCEDURE æTN $A953 æD PROCEDURE UpdtControl(theWindow: WindowPtr;updateRgn: RgnHandle); æDT UpdtControl(theWindow,updateRgn); æMM æRI UpdtControl procedure IV-53 æC [128K ROM] UpdtControl is a faster version of the DrawControls procedure. Instead of drawing all of the controls in theWindow, UpdtControl draws only the controls that are in the specified update region. UpdtControl is called in response to an update event, and is usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port (for more details, see the BeginUpdate procedure in the Window Manager chapter). Note: In general, controls are in a dialog box and are automatically drawn by the DrawDialog procedure. æKY CTabHandle,CTabPtr,ColorTable æFp Controls.p æT TYPE æC CTabPtr = ^ColorTable; CTabHandle = ^CTabPtr; ColorTable = RECORD ctSeed: LONGINT; {unique identifier for table} ctFlags: INTEGER; {high bit: 0 = PixMap; 1 = device} ctSize: INTEGER; {number of entries in CTTable} ctTable: CSpecArray; {array [0..0] of ColorSpec} END; æKY CtlCTab,CCTabPtr,CCTabHandle æFp Controls.p æT TYPE æC CCTabPtr = ^CtlCTab; CCTabHandle = ^CCTabPtr; CtlCTab = RECORD ccSeed: LONGINT; {reserved} ccRider: INTEGER; {see what you have done - reserved} ctSize: INTEGER; {usually 3 for controls} ctTable: ARRAY [0..3] OF ColorSpec; END; The contents and meaning of a control’s color table are determined by its control definition function (see “The Control Color Table Resource” section). The CTabHandle parameter used in the Color Control Manager routines provides a handle to the control color table. The components of a control color table are defined as follows: TYPE CCTabHandle = ^CCTabPtr; CCTabPtr = ^CtlCTab; CtlCTab = RECORD ccSeed: LONGINT; {not used for controls} ccRider: INTEGER; {not used for controls} ctSize: INTEGER; {number of entries in table –1} ctTable: cSpecArray {array of ColorSpec records} END; Field descriptions ccSeed The ccSeed field is unused in control color tables. ccRider The ccRider field is unused in control color tables. ctSize The ctSize field defines the number of elements in the table, minus one. For controls drawn with the standard definition procedure, this field is always 3. ctTable The ctTable field holds an array of colorSpec records. Each colorSpec is made up of a partIdentifier field and a partRGB field. The partIdentifier field holds an integer which associates an RGBColor to a particular part of the control. The definition procedures attempt to find the appropriate part identifier when preparing to draw a part. If that part identifier is not found, the first color in the table is used to draw the part. The part identifiers can appear in any order in the table. The partRGB field specifies a standard RGB color record, indicating what absolute color will be used to draw the control part found in the partIdentifier field. A standard control color table is shown in Figure 6. •••Refer to Figure 6.••• Figure 6–Control Color Table The 'cctb' resource is an exact image of this control table data structure, and is stored in the same format as 'clut' color table resources. Standard buttons, check boxes, and radio buttons use a four-element color table with part identifiers as shown below: cFrameColor (0) Frame color cBodyColor (1) Fill color for body of control cTextColor (2) Text color cThumbColor (3) Unused When highlighted, plain buttons exchange their body and text colors (colors 1 and 2); check boxes and radio buttons change their appearance without changing colors. All three types indicate deactivation by dimming their text with no change in colors. Standard scroll bars use a four-element color table with part identifiers as shown below: cFrameColor (0) Frame color, foreground color for shaft and arrows cBodyColor (1 Background color for shaft and arrows cTextColor (2) Unused cThumbColor (3) Fill color for thumb When highlighted, the arrows are filled with the foreground color (color 0) within the arrow outline. A deactivated scroll bar shows no indicator, and displays its shaft in solid background color (color 1), with no pattern. The 'cctb' resource = 0 is read into the application heap when the application starts, and serves as the default control color table. The last record in the auxiliary control list points to the default 'cctb' resource. When drawing a control, the standard control definition function searches the list for an auxiliary control record whose acOwner points to the control being drawn. If it finds such a record, it uses the color table designated by that record; if it doesn’t find one before reaching the default record at the end of the list, it uses the default color table instead. All types of controls share the same default record. The default auxiliary control record is recognized by NIL values in both its acNext and acOwner fields; the application must not change these fields. A nonstandard control definition function can use color tables of any desired size and define their contents in any way it wishes, except that part indices 1 to 127 are reserved for system definition. Any such nonstandard function should take care to bypass the defaulting mechanism just described, by allocating an explicit auxiliary record for every control it creates. æKY CursorCtl.p æKL Hide_Cursor InitCursorCtl RotateCursor Show_Cursor SpinCursor Acur acurHandle acurPtr ARROW_CURSOR CROSS_CURSOR Cursors HIDDEN_CURSOR I_BEAM_CURSOR PLUS_CURSOR WATCH_CURSOR æKY Acur,acurPtr,acurHandle æFp CursorCtl.p æT TYPE æC acurPtr = ^Acur; acurHandle = ^acurPtr; Acur = RECORD n: INTEGER; {Number of cursors ("frames of film")} index: INTEGER; { Next frame to show <for internal use>} frame1: INTEGER; {'CURS' resource id for frame #1} fill1: INTEGER; {<for internal use>} frame2: INTEGER; {'CURS' resource id for frame #2} fill2: INTEGER; {<for internal use>} frameN: INTEGER; {'CURS' resource id for frame #N} fillN: INTEGER; {<for internal use>} END; æKY Cursors,HIDDEN_CURSOR,I_BEAM_CURSOR,CROSS_CURSOR,PLUS_CURSOR,WATCH_CURSOR,ARROW_CURSOR æFp CursorCtl.p æC Cursors = (HIDDEN_CURSOR,I_BEAM_CURSOR,CROSS_CURSOR,PLUS_CURSOR,WATCH_CURSOR, ARROW_CURSOR); æKY Hide_Cursor æFp CursorCtl.p æT PROCEDURE æD PROCEDURE Hide_Cursor; æDT Hide_Cursor; æC { Hide the cursor if it is showing.This is this unit's call to the Mac HideCursor routine.Thus the Mac cursor level is decremented by one when this routine is called. } æKY InitCursorCtl æFp CursorCtl.p æT PROCEDURE æD PROCEDURE InitCursorCtl(newCursors: UNIV acurHandle); æDT InitCursorCtl(newCursors); æC { Initialize the CursorCtl unit. This should be called once prior to calling RotateCursor or SpinCursor. It need not be called if only Hide_Cursor or Show_Cursor are used. If NewCursors is NULL, InitCursorCtl loads in the 'acur' resource and the 'CURS' resources specified by the 'acur' resource ids. If any of the resources cannot be loaded, the cursor will not be changed. The 'acur' resource is assumed to either be in the currently running tool or application, or the MPW Shell for a tool, or in the System file. The 'acur' resource id must be 0 for a tool or application, 1 for the Shell, and 2 for the System file. If NewCursors is not NULL, it is ASSUMED to be a handle to an 'acur' formatted resource designated by the caller and it will be used instead of doing a GetResource on 'acur'. Note, if RotateCursor or SpinCursor are called without calling InitCursorCtl, then RotateCursor and SpinCursor will do the call for the user the first time it is called. However, the possible disadvantage of using this technique is that the resource memory allocated may have undesirable affect (fragmentation?) on the application. Using InitCursorCtl has the advantage of causing the allocation at a specific time determined by the user. Caution: InitCursorCtl MODIFIES the 'acur' resource in memory. Specifically, it changes each FrameN/fillN integer pair to a handle to the corresponding 'CURS' resource also in memory. Thus if NewCursors is not NULL when InitCursorCtl is called, the caller must guarantee NewCursors always points to a "fresh" copy of an 'acur' resource. This need only be of concern to a caller who wants to repeatly use multiple 'acur' resources during execution of their programs. } æKY RotateCursor æFp CursorCtl.p æT PROCEDURE æD PROCEDURE RotateCursor(counter: LONGINT); æDT RotateCursor(counter); æC { RotateCursor is called to rotate the "I am active" "beach ball" cursor, or to animate whatever sequence of cursors set up by InitCursorCtl. The next cursor ("frame") is used when Counter % 32 = 0 (Counter is some kind of incrementing or decrementing index maintained by the caller). A positive counter sequences forward through the cursors (e.g., it rotates the "beach ball" cursor clockwise), and a negative cursor sequences through the cursors backwards (e.g., it rotates the "beach ball" cursor counterclockwise). Note, RotateCursor just does a Mac SetCursor call for the proper cursor picture. It is assumed the cursor is visible from a prior Show_Cursor call. } æKY Show_Cursor æFp CursorCtl.p æT PROCEDURE æD PROCEDURE Show_Cursor(cursorKind: Cursors); æDT Show_Cursor(cursorKind); æC { Increment the cursor level, which may have been decremented by Hide_Cursor, and display the specified cursor if the level becomes 0 (it is never incremented beyond 0).The CursorKind is the kind of cursor to show. It is one of the values HIDDEN_CURSOR, I_BEAM_CURSOR, CROSS_CURSOR, PLUS_CURSOR, WATCH_CURSOR, and ARROW_CURSOR. Except for HIDDEN_CURSOR, a Mac SetCursor is done for the specified cursor prior to doing a ShowCursor. HIDDEN_CURSOR just causes a ShowCursor call. Note, ARROW_CURSOR will only work correctly if there is already a grafPort set up pointed to by 0(A5). } æKY SpinCursor æFp CursorCtl.p æT PROCEDURE æD PROCEDURE SpinCursor(increment: INTEGER); æDT SpinCursor(increment); æC { SpinCursor is similar in function to RotateCursor, except that instead of passing a counter, an Increment is passed an added to a counter maintained here. SpinCursor is provided for those users who do not happen to have a convenient counter handy but still want to use the spinning "beach ball" cursor, or any sequence of cursors set up by InitCursorCtl. A positive increment sequences forward through the curos (rotating the "beach ball" cursor clockwise), and a negative increment sequences backward through the cursors (rotating the "beach ball" cursor counter-clockwise). A zero value for the increment resets the counter to zero. Note, it is the increment, and not the value of the counter that determines the sequencing direction of the cursor (and hence the spin direction of the "beach ball" cursor). } æKY Desk.p æKL CloseDeskAcc OpenDeskAcc SystemClick SystemEdit SystemEvent SystemMenu SystemTask accClear accCopy accCursor accCut accEvent accMenu accPaste accRun accUndo goodbye æKY accClear æFp Desk.p æC accClear = 73; æKY accCopy æFp Desk.p æC accCopy = 71; æKY accCursor æFp Desk.p æC accCursor = 66; æKY accCut æFp Desk.p æC accCut = 70; æKY accEvent æFp Desk.p æC accEvent = 64; æKY accMenu æFp Desk.p æC accMenu = 67; æKY accPaste æFp Desk.p æC accPaste = 72; æKY accRun æFp Desk.p æC accRun = 65; æKY accUndo æFp Desk.p æC accUndo = 68; æKY CloseDeskAcc æFp Desk.p æT PROCEDURE æTN $A9B7 æD PROCEDURE CloseDeskAcc(refNum: INTEGER); æDT CloseDeskAcc(refNum); æRI CloseDeskAcc procedure I-440 æC When a system window is active and the user chooses Close from the File menu, call CloseDeskAcc to close the desk accessory. RefNum is the driver reference number for the desk accessory, which you get from the windowKind field of its window. The Desk Manager automatically closes a desk accessory if the user clicks its close box. Also, since the application heap is released when the application terminates, every desk accessory goes away at that time. æKY goodbye æFp Desk.p æC goodbye = -1; {goodbye message} æKY OpenDeskAcc æFp Desk.p æT FUNCTION æTN $A9B6 æD FUNCTION OpenDeskAcc(theAcc: Str255): INTEGER; æDT myVariable := OpenDeskAcc(theAcc); æMM æRI OpenDeskAcc function I-440 æC OpenDeskAcc opens the desk accessory having the given name and displays its window (if any) as the active window. The name is the accessory’s resource name, which you get from the Apple menu by calling the Menu Manager procedure GetItem. OpenDeskAcc calls the Resource Manager to read the desk accessory from the resource file into the application heap. You should ignore the value returned by OpenDeskAcc. If the desk accessory is successfully opened, the function result is its driver reference number. However, if the desk accessory can’t be opened, the function result is undefined; the accessory will have taken care of informing the user of the problem (such as memory full) and won’t display itself. Warning: Early versions of some desk accessories may set the current grafPort to the accessory’s port upon return from OpenDeskAcc. To be safe, you should bracket your call to OpenDeskAcc with calls to the QuickDraw procedures GetPort and SetPort, to save and restore the current port. Note: Programmers concerned about the amount of available memory should be aware that an open desk accessory uses from 1K to 3K bytes of heap space in addition to the space needed for the accessory itself. The desk accessory is responsible for determining whether there is sufficient memory for it to run; this can be done by calling SizeResource followed by ResrvMem. æKY SystemClick æFp Desk.p æT PROCEDURE æTN $A9B3 æD PROCEDURE SystemClick(theEvent: EventRecord;theWindow: WindowPtr); æDT SystemClick(theEvent,theWindow); æMM æRI SystemClick procedure I-441, P-35, 182 æC When a mouse-down event occurs and the Window Manager function FindWindow reports that the mouse button was pressed in a system window, the application should call SystemClick with the event record and the window pointer. If the given window belongs to a desk accessory, SystemClick sees that the event gets handled properly. SystemClick determines which part of the desk accessory’s window the mouse button was pressed in, and responds accordingly (similar to the way your application responds to mouse activities in its own windows). • If the mouse button was pressed in the content region of the window and the window was active, SystemClick sends the mouse-down event to the desk accessory, which processes it as appropriate. • If the mouse button was pressed in the content region and the window was inactive, SystemClick makes it the active window. • If the mouse button was pressed in the drag region, SystemClick calls the Window Manager procedure DragWindow to pull an outline of the window across the screen and move the window to a new location. If the window was inactive, DragWindow also makes it the active window (unless the Command key was pressed along with the mouse button). • If the mouse button was pressed in the go-away region, SystemClick calls the Window Manager function TrackGoAway to determine whether the mouse is still inside the go-away region when the click is completed: If so, it tells the desk accessory to close itself; otherwise, it does nothing. æKY SystemEdit æFp Desk.p æT FUNCTION æTN $A9C2 æD FUNCTION SystemEdit(editCmd: INTEGER): BOOLEAN; æDT myVariable := SystemEdit(editCmd); æMM æRT 180, 215 æRI SystemEdit function I-441 æC Assembly-language note: The macro you invoke to call SystemEdit from assembly language is named _SysEdit. Call SystemEdit when there’s a mouse-down event in the menu bar and the user chooses one of the five standard editing commands from the Edit menu. Pass one of the following as the value of the editCmd parameter: editCmd Editing command 0 Undo 2 Cut 3 Copy 4 Paste 5 Clear If your Edit menu contains these five commands in the standard arrangement (the order listed above, with a dividing line between Undo and Cut), you can simply call SystemEdit(menuItem-1) where menuItem is the menu item number. If the active window doesn’t belong to a desk accessory, SystemEdit returns FALSE; the application should then process the editing command as usual. If the active window does belong to a desk accessory, SystemEdit asks that accessory to process the command and returns TRUE; in this case, the application should ignore the command. Note: It’s up to the application to make sure desk accessories get their editing commands that are chosen from the Edit menu. In particular, make sure your application hasn’t disabled the Edit menu or any of the five standard commands when a desk accessory is activated. æKY SystemEvent æFp Desk.p æT FUNCTION æTN $A9B2 æD FUNCTION SystemEvent(theEvent: EventRecord): BOOLEAN; æDT myVariable := SystemEvent(theEvent); æRT 5,85 æRI SystemEvent function I-442, N5-1, N85-1 æC SystemEvent is called only by the Toolbox Event Manager function GetNextEvent when it receives an event, to determine whether the event should be handled by the application or by the system. If the given event should be handled by the application, SystemEvent returns FALSE; otherwise, it calls the appropriate system code to handle the event and returns TRUE. In the case of a null or mouse-down event, SystemEvent does nothing but return FALSE. Notice that it responds this way to a mouse-down event even though the event may in fact have occurred in a system window (and therefore may have to be handled by the system). The reason for this is that the check for exactly where the event occurred (via the Window Manager function FindWindow) is made later by the application and so would be made twice if SystemEvent were also to do it. To avoid this duplication, SystemEvent passes the event on to the application and lets it make the sole call to FindWindow. Should FindWindow reveal that the mouse-down event did occur in a system window, the application can then call SystemClick, as described above, to get the system to handle it. If the given event is a mouse-up or any keyboard event (including keyboard equivalents of commands), SystemEvent checks whether the active window belongs to a desk accessory and whether that accessory can handle this type of event. If so, it sends the event to the desk accessory and returns TRUE; otherwise, it returns FALSE. If SystemEvent is passed an activate or update event, it checks whether the window the event occurred in is a system window belonging to a desk accessory and whether that accessory can handle this type of event. If so, it sends the event to the desk accessory and returns TRUE; otherwise, it returns FALSE. Note: It’s unlikely that a desk accessory would not be set up to handle keyboard, activate, and update events, or that it would handle mouse-up events. If the given event is a disk-inserted event, SystemEvent does some low-level processing (by calling the File Manager function MountVol) but passes the event on to the application by returning FALSE, in case the application wants to do further processing. Finally, SystemEvent returns FALSE for network, device driver, and application-defined events. Assembly-language note: Advanced programmers can make SystemEvent always return FALSE by setting the global variable SEvtEnb (a byte) to 0. æKY SystemMenu æFp Desk.p æT PROCEDURE æTN $A9B5 æD PROCEDURE SystemMenu(menuResult: LONGINT); æDT SystemMenu(menuResult); æMM æRI SystemMenu procedure I-443 æC SystemMenu is called only by the Menu Manager functions MenuSelect and MenuKey, when an item in a menu belonging to a desk accessory has been chosen. The menuResult parameter has the same format as the value returned by MenuSelect and MenuKey: the menu ID in the high-order word and the menu item number in the low-order word. (The menu ID will be negative.) SystemMenu directs the desk accessory to perform the appropriate action for the given menu item. æKY SystemTask æFp Desk.p æT PROCEDURE æTN $A9B4 æD PROCEDURE SystemTask; æDT SystemTask; æRT 85 æRI SystemTask procedure I-442, 444, II-189, N85-1 æC For each open desk accessory (or other device driver performing periodic actions), SystemTask causes the accessory to perform the periodic action defined for it, if any such action has been defined and if the proper time period has passed since the action was last performed. For example, a clock accessory can be defined such that the second hand is to move once every second; the periodic action for the accessory will be to move the second hand to the next position, and SystemTask will alert the accessory every second to perform that action. You should call SystemTask as often as possible, usually once every time through your main event loop. Call it more than once if your application does an unusually large amount of processing each time through the loop. Note: SystemTask should be called at least every sixtieth of a second. æKY DeskBus.p æKL ADBOp ADBReInit CountADBs GetADBInfo GetIndADB SetADBInfo ADBAddress ADBDataBlock ADBDBlkPtr ADBOpBlock ADBOpBPtr ADBSetInfoBlock ADBSInfoPtr æKY ADBAddress æFp DeskBus.p æT TYPE æC ADBAddress = SignedByte; æKY ADBDataBlock,ADBDBlkPtr æFp DeskBus.p æT TYPE æC ADBDBlkPtr = ^ADBDataBlock; ADBDataBlock = PACKED RECORD devType: SignedByte; {device type} origADBAddr: SignedByte; {original ADB Address} dbServiceRtPtr: Ptr; {service routine pointer} dbDataAreaAddr: Ptr; {data area address} END; æKY ADBOp æFp Deskbus.p æT FUNCTION æTN $A07C æD FUNCTION ADBOp(data: Ptr;compRout: ProcPtr;buffer: Ptr;commandNum: INTEGER): OSErr; æDT myVariable := ADBOp(data,compRout,buffer,commandNum); æRT 206 æRI ADBOp function V-368 æC Trap macro _ADBOp On entry: A0: pointer to parameter block D0: commandNum (byte) Parameter block --> 0 buffer pointer --> 4 compRout pointer --> 8 data pointer On exit: D0: result code (byte) The completion routine pointed to by compRout will be passed the following parameters on entry: D0: commandNum (byte) A0: pointer to buffer, data stored as a Pascal string (maximum 8 bytes data preceded by one length byte) A1: pointer to completion routine (compRout) A2: pointer to optional data area (data) ADBOp transmits over the bus the command byte whose value is given by commandNum. The structure of the command byte is given earlier in Figure 1. ADBOp executes only when the ADB is otherwise idle; otherwise it is held in a command queue. It returns an error if the command queue is full. The length of the data buffer pointed to by buffer is contained in its first byte, like a Pascal string. The optional data area pointed to by data is for local storage by the completion routine pointed to by compRout. ADBop should be used sparingly; it is not intended for polling a device. The host automatically polls devices with data to deliver. Result codes noErr No error –1 Unsuccessful completion æKY ADBOpBlock,ADBOpBPtr æFp DeskBus.p æT TYPE æC ADBOpBPtr = ^ADBOpBlock; ADBOpBlock = RECORD dataBuffPtr: Ptr; {address of data buffer} opServiceRtPtr: Ptr; {service routine pointer} opDataAreaPtr: Ptr; {optional data area address} END; æKY ADBReInit æFp Deskbus.p æT PROCEDURE æTN $A07B æD PROCEDURE ADBReInit; æDT ADBReInit; æMM æRT 143, 206 æRI ADBReInit procedure V-367, N143 æC Trap macro _ADBReInit ADBReInit reinitializes the entire Apple Desktop Bus. It clears the ADB device table to zeros and places a SendReset command on the bus to reset all devices to their original addresses. ADBReInit has no parameters. Because it does not deallocate ADB resources on the system heap, ADBReInit should not be used for routine bus initialization. Apple strongly recommends against adding devices while the system is running; therefore, you should never call ADBReInit. ADBReInit also calls a routine pointed to by the low memory global JADBProc at the beginning and end of its execution. You can insert your own preprocessing/postprocessing routine by changing the value of JADBProc; ADBReInit conditions it by setting D0 to 0 for preprocessing and to 1 for postprocessing. Your procedure must restore the value of D0 and branch to the original value of JADBProc on exit. JADBProc should be used to de-allocate memory used by the driver (see MacDTS Sample Code “TbltDrvr” for an example), and then it should chain to the procedure originally found in JADBProc. The complete ADBReInit sequence is therefore the following: • JSR to JADBProc with D0 set to 0 • reinitialize the Apple Desktop Bus • clear the ADB device table • JSR to JADBProc with D0 set to 1 æKY ADBSetInfoBlock,ADBSInfoPtr æFp DeskBus.p æT TYPE æC ADBSInfoPtr = ^ADBSetInfoBlock; ADBSetInfoBlock = RECORD siServiceRtPtr: Ptr; {service routine pointer} siDataAreaAddr: Ptr; {data area address} END; æKY CountADBs æFp Deskbus.p æT FUNCTION æTN $A077 æD FUNCTION CountADBs: INTEGER; æDT myVariable := CountADBs; æRT 206 æRI CountADBs function V-369 æC Trap macro _CountADBs On exit: D0: number of devices (byte) CountADBs returns a value representing the number of devices connected to the ADB by counting the number of entries in the device table. It has no arguments and returns no error codes. æKY GetADBInfo æFp Deskbus.p æT FUNCTION æTN $A079 æD FUNCTION GetADBInfo(VAR info: ADBDataBlock;adbAddr: ADBAddress): OSErr; æDT myVariable := GetADBInfo(info,adbAddr); æRI GetADBInfo function V-370 æC Trap macro _GetADBInfo On entry: A0: pointer to parameter block D0: ADB address of the device (byte) Parameter block <-- 0 device handler ID byte <-- 1 original ADB address byte <-- 2 service routine address pointer (compRout) <-- 6 data area address pointer (data) On exit: D0: result code (byte) GetADBInfo returns information from the ADB device table entry of the device whose ADB address is given by ABDAddr. The structure of ADBDataBlock is given above under “GetIndADB”. Result codes noErr No error æKY GetIndADB æFp Deskbus.p æT FUNCTION æTN $A078 æD FUNCTION GetIndADB(VAR info: ADBDataBlock;devTableIndex: INTEGER): ADBAddress; æDT myVariable := GetIndADB(info,devTableIndex); æRT 206 æRI GetIndADB function V-369 æC Trap macro _GetIndADB On entry: A0: pointer to parameter block D0: entry index number; range = 1..CountADBs (byte) Parameter block <-- 0 device type byte (handler ID) <-- 1 original ADB address byte <-- 2 service routine address pointer (compRout) <-- 6 data area address pointer (data) On exit: D0: positive value: current ADB address (byte) negative value: error code (byte) GetIndADB returns information from the ADB device table entry whose index number is given by devTableIndex. ADBDataBlock has this form: TYPE ADBDataBlock = PACKED RECORD devType: SignedByte; {device type (handler ID)} origADBAddr: SignedByte; {original ADB address} dbServiceRtPtr: Ptr; {service routine address (compRout)} dbDataAreaAddr: Ptr {data area address (data)} END; GetIndADB returns the current ADB address of the device. If it is unable to complete execution successfully, GetIndADB returns a negative value. æKY SetADBInfo æFp Deskbus.p æT FUNCTION æTN $A07A æD FUNCTION SetADBInfo(VAR info: ADBSetInfoBlock;adbAddr: ADBAddress): OSErr; æDT myVariable := SetADBInfo(info,adbAddr); æRT 206 æRI SetADBInfo function V-370 æC Trap macro _SetADBInfo On entry: A0: pointer to parameter block D0: ADB address of the device (byte) Parameter block --> 0 service routine address pointer (compRout) --> 4 data area address pointer (data) On exit: D0: result code (byte) SetADBInfo sets the service routine address and the data area address in the ADB device table entry for the device whose ADB address is given by ABDAddr. ADBSetInfoBlock has this form: TYPE ADBSetInfoBlock = RECORD siServiceRtPtr: Ptr; {service routine address (compRout)} siDataAreaAddr: Ptr {data area address (data)} END; Result codes noErr No error Warning: You should send a Flush command to the device after calling it with SetADBInfo, to prevent it sending old data to the new data area address. æKY Devices.p æKL CloseDriver Control GetDCtlEntry KillIO OpenDriver PBControl PBKillIO PBOpenDriver PBStatus SetChooserAlert Status activDev AuxDCE AuxDCEHandle AuxDCEPtr buttonMsg cdevGenErr cdevMemErr cdevResErr cdevUnset chooserID clearDev closeDev Control Control copyDev cutDev DCtlEntry DCtlHandle DCtlPtr deactivDev deselectMsg fillListMsg getSelMsg hitDev initDev keyEvtDev macDev newSelMsg nulDev pasteDev selectMsg terminateMsg undoDev updateDev æKY PBOpenDriver æFp Devices.p æT FUNCTION æD FUNCTION PBOpenDriver(paramBlock: ParmBlkPtr): OSErr; æDT myVariable := PBOpenDriver(paramBlock); æKY activDev æFp Devices.p æC activDev = 5; {Activate event} »The activDev Message An activDev message is sent to the cdev on every activate event. It allows the cdev to reset any items that may have changed while the Control Panel was inactive. It also allows the cdev to send things such as “lists activate” messages. æKY AuxDCE,AuxDCEPtr,AuxDCEHandle æFp Devices.p æT TYPE æC AuxDCEPtr = ^AuxDCE; AuxDCEHandle = ^AuxDCEPtr; AuxDCE = PACKED RECORD dCtlDriver: Ptr; dCtlFlags: INTEGER; dCtlQHdr: QHdr; dCtlPosition: LONGINT; dCtlStorage: Handle; dCtlRefNum: INTEGER; dCtlCurTicks: LONGINT; dCtlWindow: GrafPtr; dCtlDelay: INTEGER; dCtlEMask: INTEGER; dCtlMenu: INTEGER; dCtlSlot: Byte; dCtlSlotId: Byte; dCtlDevBase: LONGINT; dCtlOwner: Ptr; dCtlExtDev: Byte; fillByte: Byte; END; æKY buttonMsg æFp Devices.p æC buttonMsg = 19; æKY cdevUnset,cdevGenErr,cdevMemErr,cdevResErr æFp Devices.p æC »CDEV ERROR CHECKING _______________________________________________________________________________ Because a desk accessory may be called into many strange and wonderful situations, careful attention must be paid to error checking. The two most common error conditions are missing resources and lack of memory. Some error reporting and recovery facilities have been provided in the Control Panel to help with errors encountered in a cdev. Because the Control Panel has no direct information about the cdev, the cdev’s code must be able to detect and recover from error conditions on its own. If the recovery cannot be effected the cdev must dispose of any memory it has allocated, and exit back to the Control Panel with an error code. Following a shutdown, the Control Panel can help report the error condition to the user and prevent accidental reentry into the cdev that might result from such things as an update event. A cdev can request three different error reporting mechanisms from the Control Panel: • If a memory error has occured, then, after the cdev has safely shut itself down, it may request the Control Panel to issue an out-of-memory error message and gray out (paint over with the background pattern) the cdev area of the Control Panel window. It will remain grayed until another cdev is selected. The Control Panel window itself is not closed since other cdevs may still be able to function in the environment. • If a resource error is detected, the cdev may request that a can’t-find-needed-resource error message be issued. • The cdev may display its own error message and then call on the Control Panel to gray its area. The Control Panel uses the cdevValue parameter to send status information to the cdev, and a proper cdev uses its function value to send information back to the Control Panel. In the absence of errors, the same value passes back and forth: the Control Panel puts the last function value it received into cdevValue when it calls the cdev; the cdev returns the value it finds there as the function value. The cdev may want to keep a handle to its own storage, in which case passing it as the function value ensures its availability, since the Control Panel will pass it back in cdevValue at the next call. Four constants have been defined for this cdev/Control Panel communication: CONST cdevUnset = 3; {initial value passed in cdevValue} cdevGenErr = -1; {generic cdev error} cdevMemErr = 0; {insufficient memory for cdev execution} cdevResErr = 1; {missing resource needed by cdev} After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until an error occurs or the cdev uses its function value as a handle, cdevUnset is passed back and forth. If the cdev encounters an error, it should dispose of all handles and pointers it has set up, strip the stack back to the same position as a normal exit, and return one of the three error codes as the function result. The Control Panel will respond as follows: Function Message to Control Panel Action Result Control Panel cdevGenErr The cdev has encountered an Gray out the cdev’s area, error from which it cannot send a 0 in cdevValue in recover, but do not put up succeeding cdev calls an error dialog. cdevMemErr The cdev has determined that Gray out cdev’s area, put there is not enough memory to up error dialog, send a 0 execute; please put up a in cdevValue in succeeding memory error dialog. cdev calls. cdevResErr The cdev can’t find a needed Gray out cdev’s area, put resource; please put up a up error dialog, send a 0 resource error dialog. in cdevValue in succeeding cdev calls. all other values, No error conditions. Send the value back in either handles cdevValue. or cdevUnset The cdev code should check cdevValue at entry. A 0 means that the Control Panel has responded to a cdev error message by shutting down the cdev and displaying an error dialog if one was requested. The cdev should immediately exit. Once the Control Panel has responded to an error message from a cdev it will no longer respond to any return values until another cdev is launched. æKY chooserID æFp Devices.p æC chooserID = 1; æKY clearDev æFp Devices.p æC clearDev = 13; æKY closeDev æFp Devices.p æC closeDev = 2; {Close yourself} »The closeDev Message A closeDev message is sent to the cdev when either the Control Panel is closed or the user selects another cdev. When a cdev receives a closeDev message it should dispose of any storage it has allocated, including the handle stored in cdevValue, if any. æKY CloseDriver æFp Devices.p æT FUNCTION æD FUNCTION CloseDriver(refNum: INTEGER): OSErr; æDT myVariable := CloseDriver(refNum); æRI CloseDriver function II-178 æC [Not in ROM] CloseDriver closes the device driver having the reference number refNum. Any pending I/O is completed, and the memory used by the driver is released. Warning: Before using this command to close a particular driver, refer to the chapter describing the driver for the consequences of closing it. Result codes noErr No error badUnitErr Bad reference number dRemoveErr Attempt to remove an open driver unitEmptyErr Bad reference number æKY Control æFp Devices.p æT FUNCTION æTN $A004 æD FUNCTION Control(refNum: INTEGER;csCode: INTEGER;csParamPtr: Ptr): OSErr; æDT myVariable := Control(refNum,csCode,csParamPtr); æMM æRI Control function high-level II-179 low-level II-186 æC [Not in ROM] Control sends control information to the device driver having the reference number refNum. The type of information sent is specified by csCode, and the information itself is pointed to by csParamPtr. The values passed in csCode and pointed to by csParamPtr depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number controlErr Driver can’t respond to this Control call æKY copyDev æFp Devices.p æC copyDev = 11; æKY cutDev æFp Devices.p æC cutDev = 10; æKY DCtlEntry,DCtlPtr,DCtlHandle æFp Devices.p æT TYPE æC DCtlPtr = ^DCtlEntry; DCtlHandle = ^DCtlPtr; DCtlEntry = RECORD dCtlDriver: Ptr; dCtlFlags: INTEGER; dCtlQHdr: QHdr; dCtlPosition: LONGINT; dCtlStorage: Handle; dCtlRefNum: INTEGER; dCtlCurTicks: LONGINT; dCtlWindow: WindowPtr; dCtlDelay: INTEGER; dCtlEMask: INTEGER; dCtlMenu: INTEGER; END; »Device Control Entry The first time a driver is opened, information about it is read into a structure in memory called a device control entry. A device control entry contains the header of the driver’s I/O queue, the location of the driver’s routines, and other information. A device control entry is a 40-byte relocatable block located in the system heap. It’s locked while the driver is open, and unlocked while the driver is closed. Most of the data in the device control entry is stored and accessed only by the Device Manager, but in some cases the driver itself must store into it. The structure of a device control entry is shown below; note that the first four words of the driver are copied into the dCtlFlags, dCtlDelay, dCtlEMask, and dCtlMenu fields. TYPE DCtlEntry = RECORD dCtlDriver: Ptr; {pointer to ROM driver or } { handle to RAM driver} dCtlFlags: INTEGER; {flags} dCtlQHdr: QHdr; {driver I/O queue header} dCtlPosition: LONGINT; {byte position used by Read } { and Write calls} dCtlStorage: Handle; {handle to RAM driver's } { private storage} dCtlRefNum: INTEGER; {driver reference number} dCtlCurTicks: LONGINT; {used internally} dCtlWindow: WindowPtr; {pointer to driver's window} dCtlDelay: INTEGER; {number of ticks between } { periodic actions} dCtlEMask: INTEGER; {desk accessory event mask} dCtlMenu: INTEGER {menu ID of menu associated { with driver} END; DCtlPtr = ^DCtlEntry; DCtlHandle = ^DCtlPtr; The low-order byte of the dCtlFlags word contains the following flags: Bit number Meaning 5 Set if driver is open 6 Set if driver is RAM-based 7 Set if driver is currently executing Assembly-language note: These flags can be accessed with the global constants dOpened, dRAMBased, and drvrActive. The high-order byte of the dCtlFlags word contains flags copied from the drvrFlags word of the driver, as described above. DCtlQHdr contains the header of the driver’s I/O queue (described below). DCtlPosition is used only by drivers of block devices, and indicates the current source or destination position of a Read or Write call. The position is given as a number of bytes beyond the physical beginning of the medium used by the device. For example, if one logical block of data has just been read from a 3 1/2-inch disk via the Disk Driver, dCtlPosition will be 512. ROM drivers generally use locations in low memory for their local storage. RAM drivers may reserve memory within their code space, or allocate a relocatable block and keep a handle to it in dCtlStorage (if the block resides in the application heap, its handle will be set to NIL when the heap is reinitialized). You can get a handle to a driver’s device control entry by calling the Device Manager function GetDCtlEntry. æKY deactivDev æFp Devices.p æC deactivDev = 6; {Deactivate event} »The deActivDev Message A deActivDev message is sent to the cdev on every deactivate event. It allows the cdev to send deactivate messages to items such as lists. æKY deselectMsg æFp Devices.p æC deselectMsg = 16; æKY fillListMsg æFp Devices.p æC fillListMsg = 13; æKY GetDCtlEntry æFp Devices.p æT FUNCTION æD FUNCTION GetDCtlEntry(refNum: INTEGER): DCtlHandle; æDT myVariable := GetDCtlEntry(refNum); æMM æRT 71 æRI GetDCtlEntry function II-190 æC [Not in ROM] GetDCtlEntry returns a handle to the device control entry of the device driver having the reference number refNum. Assembly-language note: You can get a handle to a driver’s device control entry from the unit table, as described below. æKY getSelMsg æFp Devices.p æC getSelMsg = 14; æKY hitDev æFp Devices.p æC hitDev = 1; {Hit on one of my items} »The hitDev Message A hitDev message is sent when the user has clicked an enabled dialog item that belongs to the cdev. The dialog item number of the item hit is passed in the Item parameter. Remember that the Control Panel’s items precede yours, so you’ll want (Item – numItems) to determine which of your items was hit. If the Control Panel itself has n items, the first of the cdev’s items will be n+1 in the combined dialog item list. A cdev should not depend on any hardcoded value for numItems, since the number of items in Control Panel’s 'DITL' is likely to change in the future. Factoring in numItems need not mean an increase in your code size, or passing and adding numItems everywhere, or foregoing the constants that most developers use to identify specific items. You can do it easily, and neatly, as follows: 1. Subtract numItems from Item right away, and refer to your dialog items with constants as usual throughout the cdev. 2. Write simple envelope routines to enclose Dialog Manager procedures that require item number arguments. Add numItems only locally, within those routines and for the Dialog Manager calls only. This is demonstrated in the sample cdev. æKY initDev æFp Devices.p æC initDev = 0; {Time for cdev to initialize itself} »The initDev Message InitDev is an initialization message sent to allow the cdev to allocate its private storage (if any) and do any initial settings to buttons or controls. This message is sent when the user clicks on the cdev’s icon. Note that the dialog, cdev list, and all of the items in the cdev’s 'DITL' except user items will already have been drawn when the initDev message is sent. If your cdev doesn’t need any storage it should return the value that was passed to it in cdevValue. æKY keyEvtDev æFp Devices.p æC keyEvtDev = 7; {Key down/auto key} »The keyEvtDev Message A keyEvtDev message is sent to the cdev on every keyDown event and autoKey event. It allows the cdev to process key events. On return to the Control Panel, the key event will be processed by a call to dialogSelect in the Dialog Manager. A cdev that does not want the Toolbox Event Manager to do any further processing should change the what field of the EventRecord to nullEvent before returning to the Control Panel. æKY KillIO æFp Devices.p æT FUNCTION æTN $A006 æD FUNCTION KillIO(refNum: INTEGER): OSErr; æDT myVariable := KillIO(refNum); æRI KillIO function high-level II-179 æC [Not in ROM] KillIO terminates all current and pending I/O with the device driver having the reference number refNum. Result codes noErr No error badUnitErr Bad reference number unitEmptyErr Bad reference number æKY macDev æFp Devices.p æC macDev = 8; {Decide whether or not to show up} »The macDev Message If the 'mach' resource has a 0 in Softmask and a –1 ($FFFF) in Hardmask, the first message a cdev will get is a macDev message. This is an opportunity for the cdev to determine whether it can run, and whether it should appear in the Control Panel’s cdev list. The cdev can do its own check to see which machine it is being run on, what hardware is connected, and what is in the slots (if it has slots). The cdev must then return a function result of 1 or 0. If a 0 is returned, the Control Panel will not display the cdev in the icon list. (Note that the Control Panel does not interpret this 0 or 1 as an error message as described under “Cdev Error Checking”.) The macDev call happens only once, and only when Softmask and Hardmask are 0 and FFFF. It is always the first call made to the cdev. æKY newSelMsg æFp Devices.p æC newSelMsg = 12; æKY nulDev æFp Devices.p æC nulDev = 3; {Null event} »The nulDev Message A nulDev message is sent to the cdev on every Control Panel run event. This allows the cdev to perform tasks that need to be executed continuously (insertion point blinking, for example). A cdev cannot assume any particular timing of calls from applications. Don’t use nulDev to refresh settings; see activDev, above. æKY OpenDriver æFp Devices.p æT FUNCTION æD FUNCTION OpenDriver(name: Str255;VAR drvrRefNum: INTEGER): OSErr; æDT myVariable := OpenDriver(name,drvrRefNum); æMM æRI OpenDriver function II-178, N14-2 æC [Not in ROM] OpenDriver opens the device driver specified by name and returns its reference number in refNum. Result codes noErr No error badUnitErr Bad reference number dInstErr Couldn’t find driver in resource file openErr Driver can’t perform the requested reading or writing unitEmptyErr Bad reference number æKY pasteDev æFp Devices.p æC pasteDev = 12; æKY PBControl æFp Devices.p æT FUNCTION æTN $A004 æD FUNCTION PBControl(paramBlock: ParmBlkPtr;aSync: BOOLEAN): OSErr; æDT myVariable := PBControl(paramBlock,aSync); æMM æRI PBControl function II-186 æC Trap macro _Control Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word --> 28 csParam record PBControl sends control information to the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information sent is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number controlErr Driver can’t respond to this Control call æKY PBKillIO æFp Devices.p æT FUNCTION æTN $A006 æD FUNCTION PBKillIO(paramBlock: ParmBlkPtr;aSync: BOOLEAN): OSErr; æDT myVariable := PBKillIO(paramBlock,aSync); æRI PBKillIO function II-187 æC Trap macro _KillIO Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBKillIO stops any current I/O request being processed, and removes all pending I/O requests from the I/O queue of the device driver having the reference number ioRefNum. The completion routine of each pending I/O request is called, with the ioResult field of each request equal to the result code abortErr. Result codes noErr No error badUnitErr Bad reference number unitEmptyErr Bad reference number æKY PBStatus æFp Devices.p æT FUNCTION æTN $A005 æD FUNCTION PBStatus(paramBlock: ParmBlkPtr;aSync: BOOLEAN): OSErr; æDT myVariable := PBStatus(paramBlock,aSync); æMM æRI PBStatus function II-186 æC Trap macro _Status Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word --> 24 ioRefNum word --> 26 csCode word <-- 28 csParam record PBStatus returns status information about the device driver having the reference number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information returned is specified by csCode, and the information itself begins at csParam. The values passed in csCode and csParam depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number statusErr Driver can’t respond to this Status call æKY selectMsg æFp Devices.p æC selectMsg = 15; æKY SetChooserAlert æFp Devices.p æT FUNCTION æD FUNCTION SetChooserAlert(f: BOOLEAN): BOOLEAN; æDT myVariable := SetChooserAlert(f); æRI SetChooserAlert function V-431 æC If f is true, the Chooser will put up the page setup alert; if f is false it won’t. SetChooserAlert returns the original alert state. The application should restore the original alert state when it exits. _____________________________________________________________________________________ Assembly-language note: If the psAlert bit of the low-memory global HiliteMode is 0 then no page setup alert will be generated. Applications that set or clear this bit must be sure not to affect any other bits in the byte and to restore the bit as they leave. HiliteMode equ $938 psAlert equ 6 bclr #psAlert,HiliteMode bset #psAlert,HiliteMode _____________________________________________________________________________________ æKY Status æFp Devices.p æT FUNCTION æTN $A005 æD FUNCTION Status(refNum: INTEGER;csCode: INTEGER;csParamPtr: Ptr): OSErr; æDT myVariable := Status(refNum,csCode,csParamPtr); æMM æRI Status function high-level II-179 low-level II-186 æC [Not in ROM] Status returns status information about the device driver having the reference number refNum. The type of information returned is specified by csCode, and the information itself is pointed to by csParamPtr. The values passed in csCode and pointed to by csParamPtr depend on the driver being called. Result codes noErr No error badUnitErr Bad reference number notOpenErr Driver isn’t open unitEmptyErr Bad reference number statusErr Driver can’t respond to this Status call æKY terminateMsg æFp Devices.p æC terminateMsg = 17; æKY undoDev æFp Devices.p æC undoDev = 9; æKY updateDev æFp Devices.p æC updateDev = 4; {Update event} »The updateDev Message An updateDev message is sent to the cdev on every update event. It allows the cdev to perform any updating necessary aside from the standard dialog item updating provided by the Dialog Manager. For example, if the cdev resource contains a picture of the sound control bar, it will probably be a user item, and the picture of the control bar and the volume knob should be redrawn in response to update events. Note that there is no mechanism for determining what to update, as the update region has already been reset. You must redraw all of your user items completely. æKY Dialogs.p æKL Alert CautionAlert CloseDialog CouldAlert CouldDialog DialogSelect DisposDialog DlgCopy DlgCut DlgDelete DlgPaste DrawDialog ErrorSound FindDItem FreeAlert FreeDialog GetAlrtStage GetDItem GetIText GetNewDialog HideDItem InitDialogs IsDialogEvent ModalDialog NewCDialog NewDialog NoteAlert ParamText ResetAlrtStage SelIText SetDAFont SetDItem SetIText ShowDItem StopAlert UpdtDialog AlertTemplate AlertTHndl AlertTPtr btnCtrl cancel cautionIcon chkCtrl ctrlItem DialogPeek DialogPtr DialogRecord DialogTemplate DialogTHndl DialogTPtr editText GrafPort GrafPtr iconItem IsDialogEvent itemDisable noteIcon ok picItem radCtrl resCtrl StageList statText stopIcon userItem WindowPtr æKY Alert æFp Dialogs.p æT FUNCTION æTN $A985 æD FUNCTION Alert(alertID: INTEGER;filterProc: ProcPtr): INTEGER; æDT myVariable := Alert(alertID,filterProc); æMM æRI Alert function I-418, V-284 æC This function invokes the alert defined by the alert template that has the given resource ID. It calls the current sound procedure, if any, passing it the sound number specified in the alert template for this stage of the alert. If no alert box is to be drawn at this stage, Alert returns a function result of –1; otherwise, it creates and displays the alert window for this alert and draws the alert box. Warning: If the alert template resource can’t be read, the function result is undefined. Note: Alert creates the alert window by calling NewDialog, and does the rest of its processing by calling ModalDialog. Alert repeatedly gets and handles events in the alert window until an enabled item is clicked, at which time it returns the item number. Normally you’ll then do whatever is appropriate in response to a click of that item. Alert gets each event by calling the Toolbox Event Manager function GetNextEvent. If the event is a mouse-down event outside the content region of the alert window, Alert emits sound number 1 (which should be a single beep) and gets the next event; otherwise, it filters and handles the event as described below. The filterProc parameter has the same meaning as in ModalDialog (see above). If it’s NIL, the standard filterProc function is executed, which makes the Return key or the Enter key have the same effect as clicking the default button. If you specify your own filterProc function and want to retain this feature, you must include it in your function. You can find out what the current default button is by looking at the aDefItem field of the dialog record for the alert (via the dialog pointer passed to the function). Alert handles the events for which the filterProc function returns FALSE as follows: • If the mouse button is pressed in a control, Alert calls the Control Manager procedure TrackControl. If the mouse button is released inside the control and the control is enabled, Alert returns; otherwise, it does nothing. • If the mouse button is pressed in any other enabled item, Alert simply returns. If it’s pressed in any other disabled item or in no item, or if any other event occurs, Alert does nothing. Before returning to the application with the item number, Alert removes the alert box from the screen. (It disposes of the alert window and its associated data structures, the item list, and the items.) Note: When an alert is removed, if it was overlapping the default button of a previous alert, that button’s bold outline won’t be redrawn. Note: The Alert function’s removal of the alert box would not be the desired result if the user clicked a check box or radio button; however, normally alerts contain only static text, icons, pictures, and buttons that are supposed to make the alert box go away. If your alert contains other items besides these, consider whether it might be more appropriate as a dialog. The Alert function looks for a resource of type 'actb' with the same ID as the alert. The alert color table is copied before it is passed to SetWinSize unless its ctSize field is equal to –1, indicating that the default window colors are to be used instead. The copy is made so that the color table resource can be purged without affecting the alert. The color dialog item list resource is duplicated as well, so it can be purgeable. æKY AlertTemplate,AlertTPtr,AlertTHndl æFp Dialogs.p æT TYPE æC AlertTPtr = ^AlertTemplate; AlertTHndl = ^AlertTPtr; AlertTemplate = RECORD boundsRect: Rect; itemsID: INTEGER; stages: StageList; END; »Alert Templates in Memory The data structure of an alert template is as follows: TYPE AlertTemplate = RECORD boundsRect: Rect; {becomes window's portRect} itemsID: INTEGER; {resource ID of item list} stages: StageList {alert stage information} END; BoundsRect is the rectangle that becomes the portRect of the window's grafPort. The itemsID field contains the resource ID of the item list for the alert. The information in the stages field determines exactly what should happen at each stage of the alert. It's packed into a word that has the following structure: TYPE StageList = PACKED RECORD boldItm4: 0..1; {default button item number minus 1} boxDrwn4: BOOLEAN; {TRUE if alert box to be drawn} sound4: 0..3 {sound number} boldItm3: 0..1; boxDrwn3: BOOLEAN; sound3: 0..3 boldItm2: 0..1; boxDrwn2: BOOLEAN; sound2: 0..3 boldItm1: 0..1; boxDrwn1: BOOLEAN; sound1: 0..3 END; Notice that the information is stored in reverse order—for the fourth stage first, and for the first stage last. The boldItm field indicates which button should be the default button (and therefore boldly outlined in the alert box). If the first two items in the alert’s item list are the OK button and the Cancel button, respectively, 0 will refer to the OK button and 1 to the Cancel button. The reason for this is that the value of boldItm plus 1 is interpreted as an item number, and normally items 1 and 2 are the OK and Cancel buttons, respectively. Whatever the item having the corresponding item number happens to be, a bold rounded-corner rectangle will be drawn outside its display rectangle. Note: When deciding where to place items in an alert box, be sure to allow room for any bold outlines that may be drawn. The boxDrwn field is TRUE if the alert box is to be drawn. The sound field specifies which sound should be emitted at this stage of the alert, with a number from 0 to 3 that’s passed to the current sound procedure. You can call ErrorSound to specify your own sound procedure; if you don’t, the standard sound procedure will be used (as described earlier in the “Alerts” section). You access the alert template by converting the handle returned by the Resource Manager to a template handle: TYPE AlertTHndl = ^AlertTPtr; AlertTPtr = ^AlertTemplate; Assembly-language note: Rather than offsets into the fields of the StageList data structure, there are masks for accessing the information stored for an alert stage in a stages word; they’re listed in the summary at the end of this chapter. æKY ctrlItem,btnCtrl,chkCtrl,radCtrl,resCtrl,statText,editText,iconItem,picItem,userItem,itemDisable æFp Dialogs.p æC { Item types } ctrlItem = 4; {add to following four constants} btnCtrl = 0; {standard button control} chkCtrl = 1; {standard check box control} radCtrl = 2; {standard radio button control} resCtrl = 3; {control defined in control template} statText = 8; {static text} editText = 16; {editable text (dialog only)} iconItem = 32; {icon} picItem = 64; {QuickDraw picture} userItem = 0; {application-defined item (dialog only)} itemDisable = 128; {add to any of above to disable} æKY CautionAlert æFp Dialogs.p æT FUNCTION æTN $A988 æD FUNCTION CautionAlert(alertID: INTEGER;filterProc: ProcPtr): INTEGER; æDT myVariable := CautionAlert(alertID,filterProc); æMM æRI CautionAlert function I-420 æC CautionAlert is like StopAlert except that it draws the Caution icon, which has the following resource ID: CONST cautionIcon = 2; The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 'actb' with the same ID as the alert. æKY CloseDialog æFp Dialogs.p æT PROCEDURE æTN $A982 æD PROCEDURE CloseDialog(theDialog: DialogPtr); æDT CloseDialog(theDialog); æMM æRI CloseDialog procedure I-413, P-107, 167 æC CloseDialog removes theDialog’s window from the screen and deletes it from the window list, just as when the Window Manager procedure CloseWindow is called. It releases the memory occupied by the following: • The data structures associated with the dialog window (such as the window’s structure, content, and update regions). • All the items in the dialog (except for pictures and icons, which might be shared resources), and any data structures associated with them. For example, it would dispose of the region occupied by the thumb of a scroll bar, or a similar region for some other control in the dialog. CloseDialog does not dispose of the dialog record or the item list. Figure 10 illustrates the effect of CloseDialog (and DisposDialog, described below). •••Refer to Figure 10.••• Figure 10–CloseDialog and DisposDialog Call CloseDialog when you’re done with a dialog if you supplied NewDialog or GetNewDialog with a pointer to the dialog storage (in the dStorage parameter) when you created the dialog. Note: Even if you didn’t supply a pointer to the dialog storage, you may want to call CloseDialog if you created the dialog with NewDialog. You would call CloseDialog if you wanted to keep the item list around (since, unlike GetNewDialog, NewDialog does not use a copy of the item list). æKY CouldAlert æFp Dialogs.p æT PROCEDURE æTN $A989 æD PROCEDURE CouldAlert(alertID: INTEGER); æDT CouldAlert(alertID); æMM æRI CouldAlert procedure I-420, V-285 æC CouldAlert makes the alert template having the given resource ID unpurgeable (reading it into memory if it’s not already there). It does the same for the alert window’s definition function, the alert’s item list resource, and any items defined as resources. This is useful if the alert may occur when the resource file isn’t accessible, such as during a disk copy. Warning: Like CouldDialog, CouldAlert assumes your alerts use the system font; if you’ve changed the font with SetDAFont, calling CouldAlert doesn’t make the font unpurgeable. The CouldAlert routine makes the alert color table template unpurgeable (reading it into memory if it isn’t already there), if it exists. It does the same for the alert’s color item list, if it has one. Warning: Like CouldDialog, CouldAlert doesn’t load or make 'FONT' or 'FOND' resources indicated in the color item list unpurgeable. æKY CouldDialog æFp Dialogs.p æT PROCEDURE æTN $A979 æD PROCEDURE CouldDialog(dialogID: INTEGER); æDT CouldDialog(dialogID); æMM æRI CouldDialog procedure I-415, V-284 æC CouldDialog makes the dialog template having the given resource ID unpurgeable (reading it into memory if it’s not already there). It does the same for the dialog window’s definition function, the dialog’s item list resource, and any items defined as resources. This is useful if the dialog box may come up when the resource file isn’t accessible, such as during a disk copy. Warning: CouldDialog assumes your dialogs use the system font; if you’ve changed the font with SetDAFont, calling CouldDialog doesn’t make the font unpurgeable. The CouldDialog procedure makes the dialog color table template unpurgeable (reading it into memory if it isn’t already there), if it exists. It does the same for the dialog’s color item list, if it has one. Warning: CouldDialog doesn’t load or make 'FONT' or 'FOND' resources indicated in the color item list unpurgeable. æKY DialogPtr,WindowPtr,GrafPtr,GrafPort æFp Dialogs.p æT TYPE æC GrafPtr = ^GrafPort; WindowPtr = GrafPtr; DialogPtr = WindowPtr; GrafPort = RECORD device: INTEGER; portBits: BitMap; portRect: Rect; visRgn: RgnHandle; clipRgn: RgnHandle; bkPat: Pattern; fillPat: Pattern; pnLoc: Point; pnSize: Point; pnMode: INTEGER; pnPat: Pattern; pnVis: INTEGER; txFont: INTEGER; txFace: Style; {txFace is unpacked byte but push as short} txMode: INTEGER; txSize: INTEGER; spExtra: Fixed; fgColor: LONGINT; bkColor: LONGINT; colrBit: INTEGER; patStretch: INTEGER; picSave: Handle; rgnSave: Handle; polySave: Handle; grafProcs: QDProcsPtr; END; »Dialog Pointers There are two types of dialog pointer, DialogPtr and DialogPeek, analogous to the window pointer types WindowPtr and WindowPeek. Most programmers will only need to use DialogPtr. The Dialog Manager defines the following type of dialog pointer: TYPE DialogPtr = WindowPtr; It can do this because the first field of a dialog record contains the window record for the dialog window. This type of pointer can be used to access fields of the window record or can be passed to Window Manager routines that expect window pointers as parameters. Since the WindowPtr data type is itself defined as GrafPtr, this type of dialog pointer can also be used to access fields of the dialog window’s grafPort or passed to QuickDraw routines that expect pointers to grafPorts as parameters. For programmers who want to access dialog record fields beyond the window record, the Dialog Manager also defines the following type of dialog pointer: TYPE DialogPeek = ^DialogRecord; Assembly-language note: From assembly language, of course, there’s no type checking on pointers, and the two types of pointer are equal. _______________________________________________________________________________ »The DialogRecord Data Type For those who want to know more about the data structure of a dialog record, the exact structure is given here. TYPE DialogRecord = RECORD window: WindowRecord; {dialog window} items: Handle; {item list} textH: TEHandle; {current editText item} editField: INTEGER; {editText item number minus 1} editOpen: INTEGER; {used internally} aDefItem: INTEGER {default button item number} END; The window field contains the window record for the dialog window. The items field contains a handle to the item list used for the dialog. (Remember that after reading an item list from a resource file, the Dialog Manager makes a copy of it and uses that copy.) Note: To get or change information about an item in a dialog, you pass the dialog pointer and the item number to a Dialog Manager procedure. You’ll never access information directly through the handle to the item list. The Dialog Manager uses the next three fields when there are one or more editText items in the dialog. If there’s more than one such item, these fields apply to the one that currently is selected or displays the insertion point. The textH field contains the handle to the edit record used by TextEdit. EditField is 1 less than the item number of the current editText item, or –1 if there’s no editText item in the dialog. The editOpen field is used internally by the Dialog Manager. Note: Actually, a single edit record is shared by all editText items; any changes you make to it will apply to all such items. See the TextEdit chapter for details about what kinds of changes you can make. The aDefItem field is used for modal dialogs and alerts, which are treated internally as special modal dialogs. It contains the item number of the default button. The default button for a modal dialog is the first item in the item list, so this field contains 1 for modal dialogs. The default button for an alert is specified in the alert template; see the following section for more information. _______________________________________________________________________________ »THE DRAWING ENVIRONMENT: GRAFPORT _______________________________________________________________________________ A grafPort is a complete drawing environment that defines where and how graphic operations will take place. You can have many grafPorts open at once, and each one will have its own coordinate system, drawing pattern, background pattern, pen size and location, character font and style, and bit map in which drawing takes place. You can instantly switch from one port to another. GrafPorts are the structures upon which a program builds windows, which are fundamental to the Macintosh “overlapping windows” user interface. Besides being used for windows on the screen, grafPorts are used for printing and for off-screen drawing. A grafPort is defined as follows: TYPE GrafPtr = ^GrafPort; GrafPort = RECORD device: INTEGER; {device-specific information} portBits: BitMap; {grafPort's bit map} portRect: Rect; {grafPort's rectangle} visRgn: RgnHandle; {visible region} clipRgn: RgnHandle; {clipping region} bkPat: Pattern; {background pattern} fillPat: Pattern; {fill pattern} pnLoc: Point; {pen location} pnSize: Point; {pen size} pnMode: INTEGER; {pen's transfer mode} pnPat: Pattern; {pen pattern} pnVis: INTEGER; {pen visibility} txFont: INTEGER; {font number for text} txFace: Style; {text's character style} txMode: INTEGER; {text's transfer mode} txSize: INTEGER; {font size for text} spExtra: Fixed; {extra space} fgColor: LONGINT; {foreground color} bkColor: LONGINT; {background color} colrBit: INTEGER; {color bit} patStretch: INTEGER; {used internally} picSave: Handle; {picture being saved} rgnSave: Handle; {region being saved} polySave: Handle; {polygon being saved} grafProcs: QDProcsPtr {low-level drawing routines} END; Note that picSave is a Handle used internally by QuickDraw while it is saving a picture, and rgnSave and polySave are used by QuickDraw as flags; they are set to “1” when the corresponding action is taking place. All QuickDraw operations refer to grafPorts via grafPtrs. (For historical reasons, grafPort is one of the few objects in the Macintosh system software that’s referred to by a pointer rather than a handle.) Warning: You can access all fields and subfields of a grafPort normally, but you should not store new values directly into them. QuickDraw has routines for altering all fields of a grafPort, and using these routines ensures that changing a grafPort produces no unusual side effects. The device field of a grafPort contains device-specific information that’s used by the Font Manager to achieve the best possible results when drawing text in the grafPort. There may be physical differences in the same logical font for different output devices, to ensure the highest-quality printing on the device being used. The default value of the device field is 0, for best results on output to the screen. For more information, see the Font Manager chapter. The portBits field is the bit map that points to the bit image to be used by the grafPort. The default bit map uses the entire screen as its bit image. The bit map may be changed to indicate a different structure in memory: All graphics routines work in exactly the same way regardless of whether their effects are visible on the screen. A program can, for example, prepare an image to be printed on a printer without ever displaying the image on the screen, or develop a picture in an off-screen bit map before transferring it to the screen. The portBits.bounds rectangle determines the coordinate system of the grafPort; all other coordinates in the grafPort are expressed in this system. The portRect field is a rectangle that defines a subset of the bit map that will be used for drawing: All drawing done by the application occurs inside the portRect. Its coordinates are in the coordinate system defined by the portBits.bounds rectangle. The portRect usually falls within the portBits.bounds rectangle, but it’s not required to do so. The portRect usually defines the “writable” interior area of a window, document, or other object on the screen. The visRgn field is manipulated by the Window Manager; you will normally never change a grafPort’s visRgn. It indicates the region of the grafPort that’s actually visible on the screen, that is, the part of the window that’s not covered by other windows. For example, if you move one window in front of another, the Window Manager logically removes the area of overlap from the visRgn of the window in back. When you draw into the back window, whatever’s being drawn is clipped to the visRgn so that it doesn’t run over onto the front window. The default visRgn is set to the portRect. The clipRgn is the grafPort’s clipping region, an arbitrary region that you can use to limit drawing to any region within the portRect. If, for example, you want to draw a half circle on the screen, you can set the clipRgn to half the square that would enclose the whole circle, and then draw the whole circle. Only the half within the clipRgn will actually be drawn in the grafPort. The default clipRgn is set arbitrarily large, you have full control over its setting; as a matter of recommended programming practice, it is advisable to make the default clipRgn rectangle smaller. Figure 10 illustrates a typical bit map (as defined by portBits), portRect, visRgn, and clipRgn. •••Refer to Figure 10.••• Figure 10–GrafPort Regions The bkPat and fillPat fields of a grafPort contain patterns used by certain QuickDraw routines. BkPat is the “background” pattern that’s used when an area is erased or when bits are scrolled out of it. When asked to fill an area with a specified pattern, QuickDraw stores the given pattern in the fillPat field and then calls a low-level drawing routine that gets the pattern from that field. The various graphic operations are discussed in detail later in the descriptions of individual QuickDraw routines. Of the next ten fields, the first five determine characteristics of the graphics pen and the last five determine characteristics of any text that may be drawn; these are described in separate sections below. The fgColor, bkColor, and colrBit fields contain values related to drawing in color. FgColor is the grafPort’s foreground color and bkColor is its background color. ColrBit tells the color imaging software which plane of the color picture to draw into. For more information, see “Drawing in Color” in the section “General Discussion of Drawing”. The patStretch field is used during output to a printer to expand patterns if necessary. The application should not change its value. The picSave, rgnSave, and polySave fields reflect the state of picture, region, and polygon definition, respectively. The application shouldn’t be concerned about exactly what information the handle, if any, leads to; you may, however, save the current value of rgnSave, set the field to NIL to disable the region definition, and later restore it to the saved value to resume the region definition. The picSave and polySave fields work similarly for pictures and polygons. Finally, the grafProcs field may point to a special data structure that the application stores into if it wants to customize QuickDraw drawing routines or use QuickDraw in other advanced, highly specialized ways (see “Customizing QuickDraw Operations”). If grafProcs is NIL, QuickDraw responds in the standard ways described in this chapter. _______________________________________________________________________________ »Pen Characteristics The pnLoc, pnSize, pnMode, pnPat, and pnVis fields of a grafPort deal with the graphics “pen”. Each grafPort has one and only one such pen, which is used for drawing lines, shapes, and text. The pen has four characteristics: a location, a size (height and width), a drawing mode, and a drawing pattern (see Figure 11). •••Refer to Figure 11.••• Figure 11–A Graphics Pen The pnLoc field specifies the point where QuickDraw will begin drawing the next line, shape, or character. It can be anywhere on the coordinate plane: There are no restrictions on the movement or placement of the pen. Remember that the pen location is a point in the grafPort’s coordinate system, not a pixel in a bit image. The top left corner of the pen is at the pen location; the pen hangs below and to the right of this point. The pen is rectangular in shape, and its width and height are specified by pnSize. The default size is a 1-by-1-bit square; the width and height can range from (0,0) to (30000,30000). If either the pen width or the pen height is less than 1, the pen will not draw. The pnMode and pnPat fields of a grafPort determine how the bits under the pen are affected when lines or shapes are drawn. The pnPat is a pattern that’s used like the “ink” in the pen. This pattern, like all other patterns drawn in the grafPort, is always aligned with the port’s coordinate system: The top left corner of the pattern is aligned with the top left corner of the portRect, so that adjacent areas of the same pattern will blend into a continuous, coordinated pattern. The pnMode field determines how the pen pattern is to affect what’s already in the bit image when lines or shapes are drawn. When the pen draws, QuickDraw first determines what bits in the bit image will be affected and finds their corresponding bits in the pattern. It then does a bit-by-bit comparison based on the pen mode, which specifies one of eight Boolean operations to perform. The resulting bit is stored into its proper place in the bit image. The pen modes are described under “Transfer Modes” in the section “General Discussion of Drawing”. The pnVis field determines the pen’s visibility, that is, whether it draws on the screen. For more information, see the descriptions of HidePen and ShowPen under “Pen and Line-Drawing Routines” in the “QuickDraw Routines” section. _______________________________________________________________________________ »Text Characteristics The txFont, txFace, txMode, txSize, and spExtra fields of a grafPort determine how text will be drawn—the font, style, and size of characters and how they will be placed in the bit image. QuickDraw can draw characters as quickly and easily as it draws lines and shapes, and in many prepared fonts. Font means the complete set of characters of one typeface. The characters may be drawn in any size and character style (that is, with stylistic variations such as bold, italic, and underline). Figure 12 shows two characters drawn by QuickDraw and some terms associated with drawing text. •••Refer to Figure 12.••• Figure 12–QuickDraw Characters Text is drawn with the base line positioned at the pen location. The txFont field is a font number that identifies the character font to be used in the grafPort. The font number 0 represents the system font. For more information about the system font, the other font numbers recognized by the Font Manager, and the construction, layout, and loading of fonts, see the Font Manager chapter. A character font is defined as a collection of images that make up the individual characters of the font. The characters can be of unequal widths, and they’re not restricted to their “cells”: The lower curl of a lowercase j, for example, can stretch back under the previous character (typographers call this kerning). A font can consist of up to 255 distinct characters, yet not all characters need to be defined in a single font. In addition, each font contains a missing symbol to be drawn in case of a request to draw a character that’s missing from the font. The txFace field controls the character style of the text with values from the set defined by the Style data type: TYPE StyleItem = (bold,italic,underline,outline,shadow,condense,extend); Style = SET OF StyleItem; Assembly-language note: In assembly language, this set is stored as a word whose low-order byte contains bits representing the style. The bit numbers are specified by the following global constants: boldBit .EQU 0 italicBit .EQU 1 ulineBit .EQU 2 outlineBit .EQU 3 shadowBit .EQU 5 extendBit .EQU 6 If all bits are 0, it represents the plain character style. You can apply stylistic variations either alone or in combination; Figure 13 illustrates some as applied to the Geneva font. Most combinations usually look good only for large font sizes. •••Refer to Figure 13.••• Figure 13–Stylistic Variations If you specify bold, each character is repeatedly drawn one bit to the right an appropriate number of times for extra thickness. Italic adds an italic slant to the characters. Character bits above the base line are skewed right; bits below the base line are skewed left. Underline draws a line below the base line of the characters. If part of a character descends below the base line (as “y” in Figure 13), the underline isn’t drawn through the pixel on either side of the descending part. Outline makes a hollow, outlined character rather than a solid one. Shadow also makes an outlined character, but the outline is thickened below and to the right of the character to achieve the effect of a shadow. If you specify bold along with outline or shadow, the hollow part of the character is widened. Condense and extend affect the horizontal distance between all characters, including spaces. Condense decreases the distance between characters and extend increases it, by an amount that the Font Manager determines is appropriate. The txMode field controls the way characters are placed in the bit image. It functions much like a pnMode: When a character is drawn, QuickDraw determines which bits in the bit image will be affected, does a bit-by-bit comparison based on the mode, and stores the resulting bits into the bit image. These modes are described under “Transfer Modes” in the section “General Discussion of Drawing”. Only three of them—srcOr, srcXor, and srcBic—should be used for drawing text. Note: If you use scrCopy, some extra blank space will be appended at the end of the text. The txSize field specifies the font size in points (where “point” is a typographical term meaning approximately 1/72 inch). Any size from 1 to 127 points may be specified. If the Font Manager doesn’t have the font in a specified size, it will scale a size it does have as necessary to produce the size desired. A value of 0 in this field represents the system font size (12 points). Finally, the spExtra field is useful when a line of characters is to be drawn justified such that it’s aligned with both a left and a right margin (sometimes called “full justification”). SpExtra contains a fixed-point number equal to the average number of pixels by which each space character should be widened to fill out the line. The Fixed data type is described in the Macintosh Memory Management: An Introduction chapter. _______________________________________________________________________________ »COORDINATES IN GRAFPORTS _______________________________________________________________________________ Each grafPort has its own local coordinate system. All fields in the grafPort are expressed in these coordinates, and all calculations and actions performed in QuickDraw use the local coordinate system of the currently selected port. Two things are important to remember: • Each grafPort maps a portion of the coordinate plane into a similarly- sized portion of a bit image. • The portBits.bounds rectangle defines the local coordinates for a grafPort. The top left corner of portBits.bounds is always aligned around the first bit in the bit image; the coordinates of that corner “anchor” a point on the grid to that bit in the bit image. This forms a common reference point for multiple grafPorts that use the same bit image (such as the screen); given a portBits.bounds rectangle for each port, you know that their top left corners coincide. The relationship between the portBits.bounds and portRect rectangles is very important: The portBits.bounds rectangle establishes a coordinate system for the port, and the portRect rectangle indicates the section of the coordinate plane (and thus the bit image) that will be used for drawing. The portRect usually falls inside the portBits.bounds rectangle, but it’s not required to do so. When a new grafPort is created, its bit map is set to point to the entire screen, and both the portBits.bounds and the portRect are set to rectangles enclosing the screen. The point (0,0) corresponds to the screen’s top left corner. You can redefine the local coordinates of the top left corner of the grafPort’s portRect, using the SetOrigin procedure. This offsets the coordinates of the grafPort’s portBits.bounds rectangle, recalculating the coordinates of all points in the grafPort to be relative to the new corner coordinates. For example, consider these procedure calls: SetPort(gamePort); SetOrigin(90,80) The call to SetPort sets the current grafPort to gamePort; the call to SetOrigin changes the local coordinates of the top left corner of that port’s portRect to (90,80) (see Figure 14). •••Refer to Figure 14.••• Figure 14–Changing Local Coordinates This offsets the coordinates of the following elements: gamePort^.portBits.bounds gamePort^.portRect gamePort^.visRgn These three elements are always kept “in sync”. Notice that when the local coordinates of a grafPort are offset, the grafPort’s clipRgn and pen location are not offset. A good way to think of it is that the port’s structure “sticks” to the screen, while the document in the grafPort (along with the pen and clipRgn) “sticks” to the coordinate system. For example, in Figure 14, before SetOrigin, the visRgn and clipRgn are the same as the portRect. After the SetOrigin call, the locations of portBits.bounds, portRect, and visRgn do not change on the screen; their coordinates are simply offset. As always, the top left corner of portBits.bounds remains “anchored” around the first bit in the bit image (the first pixel on the screen); the image on the screen doesn’t move as a result of SetOrigin. However, the pen location and clipRgn do move on the screen; the top left corner of the clipRgn is still (100,100), but this location has moved down and to the right, and the pen has similarly moved. If you’re moving, comparing, or otherwise dealing with mathematical items in different grafPorts (for example, finding the intersection of two regions in two different grafPorts), you must adjust to a common coordinate system before you perform the operation. A QuickDraw procedure, LocalToGlobal, lets you convert a point’s local coordinates to a global coordinate system where the top left corner of the bit image is (0,0); by converting the various local coordinates to global coordinates, you can compare and mix them with confidence. For more information, see the description of LocaltoGlobal under “Calculations with Points” in the “QuickDraw Routines” section. æKY DialogRecord,DialogPeek æFp Dialogs.p æT RECORD æC DialogPeek = ^DialogRecord; DialogRecord = RECORD window: WindowRecord; items: Handle; textH: TEHandle; editField: INTEGER; editOpen: INTEGER; aDefItem: INTEGER; END; »The DialogRecord Data Type For those who want to know more about the data structure of a dialog record, the exact structure is given here. TYPE DialogRecord = RECORD window: WindowRecord; {dialog window} items: Handle; {item list} textH: TEHandle; {current editText item} editField: INTEGER; {editText item number minus 1} editOpen: INTEGER; {used internally} aDefItem: INTEGER {default button item number} END; The window field contains the window record for the dialog window. The items field contains a handle to the item list used for the dialog. (Remember that after reading an item list from a resource file, the Dialog Manager makes a copy of it and uses that copy.) Note: To get or change information about an item in a dialog, you pass the dialog pointer and the item number to a Dialog Manager procedure. You’ll never access information directly through the handle to the item list. The Dialog Manager uses the next three fields when there are one or more editText items in the dialog. If there’s more than one such item, these fields apply to the one that currently is selected or displays the insertion point. The textH field contains the handle to the edit record used by TextEdit. EditField is 1 less than the item number of the current editText item, or –1 if there’s no editText item in the dialog. The editOpen field is used internally by the Dialog Manager. Note: Actually, a single edit record is shared by all editText items; any changes you make to it will apply to all such items. See the TextEdit chapter for details about what kinds of changes you can make. The aDefItem field is used for modal dialogs and alerts, which are treated internally as special modal dialogs. It contains the item number of the default button. The default button for a modal dialog is the first item in the item list, so this field contains 1 for modal dialogs. The default button for an alert is specified in the alert template; see the following section for more information. æKY DialogSelect æFp Dialogs.p æT FUNCTION æTN $A980 æD FUNCTION DialogSelect(theEvent: EventRecord;VAR theDialog: DialogPtr; VAR itemHit: INTEGER): BOOLEAN; æDT myVariable := DialogSelect(theEvent,theDialog,itemHit); æMM æRT 34 æRI DialogSelect function I-417, N34-3, P-108, 168 æC You’ll normally call DialogSelect when IsDialogEvent returns TRUE, passing in theEvent an event that needs to be handled as part of a modeless dialog. DialogSelect handles the event as described below. If the event involves an enabled dialog item, DialogSelect returns a function result of TRUE with the dialog pointer in theDialog and the item number in itemHit; otherwise, it returns FALSE with theDialog and itemHit undefined. Normally when DialogSelect returns TRUE, you’ll do whatever is appropriate as a response to the event, and when it returns FALSE you’ll do nothing. If the event is an activate or update event for a dialog window, DialogSelect activates or updates the window and returns FALSE. If the event is a mouse-down event in an editText item, DialogSelect responds as appropriate (displaying a caret at the insertion point or selecting text). If it’s a key-down or auto-key event and there’s an editText item, text entry and editing are handled in the standard way. In either case, DialogSelect returns TRUE if the editText item is enabled or FALSE if it’s disabled. If a key-down or auto-key event is passed when there’s no editText item, DialogSelect returns FALSE. Note: For a keyboard event, DialogSelect doesn’t check to see whether the Command key is held down; to handle keyboard equivalents of commands, you have to check for them before calling DialogSelect. Similarly, to treat a typed character in a special way (such as ignore it, or make it have the same effect as another character or as clicking a button), you need to check for a key-down event with that character before calling DialogSelect. If the event is a mouse-down event in a control, DialogSelect calls the Control Manager function TrackControl. If the mouse button is released inside the control and the control is enabled, DialogSelect returns TRUE; otherwise, it returns FALSE. If the event is a mouse-down event in any other enabled item, DialogSelect returns TRUE. If it’s a mouse-down event in any other disabled item or in no item, or if it’s any other event, DialogSelect returns FALSE. Note: If the event isn’t one that DialogSelect specifically checks for (if it’s a null event, for example), and there’s an editText item in the dialog, DialogSelect calls the TextEdit procedure TEIdle to make the caret blink. æKY DialogTemplate,DialogTPtr,DialogTHndl æFp Dialogs.p æT TYPE æC DialogTPtr = ^DialogTemplate; DialogTHndl = ^DialogTPtr; DialogTemplate = RECORD boundsRect: Rect; procID: INTEGER; visible: BOOLEAN; filler1: BOOLEAN; goAwayFlag: BOOLEAN; filler2: BOOLEAN; refCon: LONGINT; itemsID: INTEGER; title: Str255; END; »Dialog Templates in Memory The data structure of a dialog template is as follows: TYPE DialogTemplate = RECORD boundsRect: Rect; {becomes window's portRect} procID: INTEGER; {window definiton ID} visible: BOOLEAN; {TRUE if visible} filler1: BOOLEAN; {not used} goAwayFlag: BOOLEAN; {TRUE if has go-away region} filler2: BOOLEAN; {not used} refCon: LONGINT; {window's reference value} itemsID: INTEGER; {resource ID of item list} title: Str255 {window's title} END; The filler1 and filler2 fields are there because for historical reasons the goAwayFlag and refCon fields have to begin on a word boundary. The itemsID field contains the resource ID of the dialog’s item list. The other fields are the same as the parameters of the same name in the NewDialog function; they provide information about the dialog window. You access the dialog template by converting the handle returned by the Resource Manager to a template handle: TYPE DialogTHndl = ^DialogTPtr; DialogTPtr = ^DialogTemplate; æKY DisposDialog æFp Dialogs.p æT PROCEDURE æTN $A983 æD PROCEDURE DisposDialog(theDialog: DialogPtr); æDT DisposDialog(theDialog); æRI DisposDialog procedure I-415 æC DisposDialog calls CloseDialog (above) and then releases the memory occupied by the dialog’s item list and dialog record. Call DisposDialog when you’re done with a dialog if you let the dialog record be allocated in the heap when you created the dialog (by passing NIL as the dStorage parameter to NewDialog or GetNewDialog). æKY DlgCopy æFp Dialogs.p æT PROCEDURE æD PROCEDURE DlgCopy(theDialog: DialogPtr); æDT DlgCopy(theDialog); æMM æRT 215 æRI DlgCopy procedure I-418, P-110 æC [Not in ROM] DlgCopy is the same as DlgCut (above) except that it calls TECopy, for handling the Copy command. æKY DlgCut æFp Dialogs.p æT PROCEDURE æD PROCEDURE DlgCut(theDialog: DialogPtr); æDT DlgCut(theDialog); æRT 215 æRI DlgCut procedure I-418, P-110 æC [Not in ROM] DlgCut checks whether theDialog has any editText items and, if so, applies the TextEdit procedure TECut to the currently selected editText item. (If the dialog record’s editField is 0 or greater, DlgCut passes the contents of the textH field to TECut.) You can call DlgCut to handle the editing command Cut when a modeless dialog window is active. Assembly-language note: Assembly-language programmers can just read the dialog record’s fields and call TextEdit directly. æKY DlgDelete æFp Dialogs.p æT PROCEDURE æD PROCEDURE DlgDelete(theDialog: DialogPtr); æDT DlgDelete(theDialog); æMM æRT 215 æRI DlgDelete procedure I-418, P-110 æC [Not in ROM] DlgDelete is the same as DlgCut (above) except that it calls TEDelete, for handling the Clear command. æKY DlgPaste æFp Dialogs.p æT PROCEDURE æD PROCEDURE DlgPaste(theDialog: DialogPtr); æDT DlgPaste(theDialog); æMM æRT 215 æRI DlgPaste procedure I-418, P-110 æC [Not in ROM] DlgPaste is the same as DlgCut (above) except that it calls TEPaste, for handling the Paste command. æKY DrawDialog æFp Dialogs.p æT PROCEDURE æTN $A981 æD PROCEDURE DrawDialog(theDialog: DialogPtr); æDT DrawDialog(theDialog); æMM æRI DrawDialog procedure I-418 æC DrawDialog draws the contents of the given dialog box. Since DialogSelect and ModalDialog handle dialog window updating, this procedure is useful only in unusual situations. You would call it, for example, to display a dialog box that doesn’t require any response but merely tells the user what’s going on during a time-consuming process. æKY ErrorSound æFp Dialogs.p æT PROCEDURE æTN $A98C æD PROCEDURE ErrorSound(soundProc: ProcPtr); æDT ErrorSound(soundProc); æRI ErrorSound procedure I-411 æC ErrorSound sets the sound procedure for alerts to the procedure pointed to by soundProc; if you don’t call ErrorSound, the Dialog Manager uses the standard sound procedure. (For details, see the “Alerts” section.) If you pass NIL for soundProc, there will be no sound (or menu bar blinking) at all. Assembly-language note: The address of the sound procedure being used is stored in the global variable DABeeper. æKY FindDItem æFp Dialogs.p æT FUNCTION æTN $A984 æD FUNCTION FindDItem(theDialog: DialogPtr;thePt: Point): INTEGER; æDT myVariable := FindDItem(theDialog,thePt); æMM æRT 112 æRI FindDItem function IV-60, N112 æC FindDItem returns the item number of the item containing the point specified, in local coordinates, by thePt. If the point doesn’t lie within the item’s rectangle, FindDItem returns –1. If there are overlapping items, it returns the item number of the first item in the list containing the point. FindDItem is useful for changing the cursor when it’s over a particular item. Note: FindDItem will return the item number of disabled items as well. æKY FreeAlert æFp Dialogs.p æT PROCEDURE æTN $A98A æD PROCEDURE FreeAlert(alertID: INTEGER); æDT FreeAlert(alertID); æMM æRI FreeAlert procedure I-420, V-285 æC Given the resource ID of an alert template previously specified in a call to CouldAlert, FreeAlert undoes the effect of CouldAlert (by making the resources purgeable). It should be called when there’s no longer a need to keep the resources in memory. Given the resource ID of an alert template previously specified in a call to CouldAlert, the FreeAlert routine undoes the effect of CouldAlert, by restoring the original purge state of the color table and color item list resources. æKY FreeDialog æFp Dialogs.p æT PROCEDURE æTN $A97A æD PROCEDURE FreeDialog(dialogID: INTEGER); æDT FreeDialog(dialogID); æMM æRI FreeDialog procedure I-415, V-284 æC Given the resource ID of a dialog template previously specified in a call to CouldDialog, FreeDialog undoes the effect of CouldDialog (by making the resources purgeable). It should be called when there’s no longer a need to keep the resources in memory. Given the resource ID of a dialog template previously specified in a call to CouldDialog, the FreeDialog routine undoes the effect of CouldDialog, by restoring the original purge state of the color table and color item list resources. æKY GetAlrtStage æFp Dialogs.p æT FUNCTION æD FUNCTION GetAlrtStage: INTEGER; æDT myVariable := GetAlrtStage; æRI GetAlrtStage function I-422 æC GetAlrtStage returns the stage of the last occurrence of an alert, as a number from 0 to 3. Assembly-language note: Assembly-language programmers can get this number by accessing the global variable ACount. In addition, the global variable ANumber contains the resource ID of the alert template of the last alert that occurred. æKY GetDItem æFp Dialogs.p æT PROCEDURE æTN $A98D æD PROCEDURE GetDItem(theDialog: DialogPtr;itemNo: INTEGER;VAR itemType: INTEGER; VAR item: Handle;VAR box: Rect); æDT GetDItem(theDialog,itemNo,itemType,item,box); æMM æRI GetDItem procedure I-421 æC GetDItem returns in its VAR parameters the following information about the item numbered itemNo in the given dialog’s item list: In the itemType parameter, the item type; in the item parameter, a handle to the item (or, for item type userItem, the procedure pointer); and in the box parameter, the display rectangle for the item. Suppose, for example, that you want to change the title of a control in a dialog box. You can get the item handle with GetDItem, coerce it to type ControlHandle, and call the Control Manager procedure SetCTitle to change the title. Similarly, to move the control or change its size, you would call MoveControl or SizeControl. Note: To access the text of a statText or editText item, you can pass the handle returned by GetDItem to GetIText or SetIText (see below). æKY GetIText æFp Dialogs.p æT PROCEDURE æTN $A990 æD PROCEDURE GetIText(item: Handle;VAR text: Str255); æDT GetIText(item,text); æRT 18 æRI GetIText procedure I-422, N18-2 æC Given a handle to a statText or editText item in a dialog box, as returned by GetDItem, GetIText returns the text of the item in the text parameter. (If the user typed more than 255 characters in an editText item, GetIText returns only the first 255.) æKY GetNewDialog æFp Dialogs.p æT FUNCTION æTN $A97C æD FUNCTION GetNewDialog(dialogID: INTEGER;dStorage: Ptr;behind: WindowPtr): DialogPtr; æDT myVariable := GetNewDialog(dialogID,dStorage,behind); æMM æRT 4,34 æRI GetNewDialog function I-413, V-284, N4-1, P-107, 172 æC Like NewDialog (above), GetNewDialog creates a dialog as specified by its parameters and returns a pointer to the new dialog. Instead of having the parameters boundsRect, title, visible, procID, goAwayFlag, and refCon, GetNewDialog has a single dialogID parameter, where dialogID is the resource ID of a dialog template that supplies the same information as those parameters. The dialog template also contains the resource ID of the dialog’s item list. After calling the Resource Manager to read the item list into memory (if it’s not already in memory), GetNewDialog makes a copy of the item list and uses that copy; thus you may have multiple independent dialogs whose items have the same types, locations, and initial contents. The dStorage and behind parameters of GetNewDialog have the same meaning as in NewDialog. Warning: If either the dialog template resource or the item list resource can’t be read, the function result is undefined. Note: GetNewDialog doesn’t release the memory occupied by the resources. The GetNewDialog routine will attempt to load a 'dctb' resource and returns a pointer to a color grafPort if the resource exists. If no 'dctb' resource is present, GetNewDialog returns a pointer to an old grafPort. The dialog color table is copied before it is passed to SetWinSize unless its ctSize field is equal to –1, indicating that the default window colors are to be used instead. The copy is made so that the color table resource can be purged without affecting the dialog. The color dialog item list resource is duplicated as well, so it can be purgeable. æKY HideDItem æFp Dialogs.p æT PROCEDURE æTN $A827 æD PROCEDURE HideDItem(theDialog: DialogPtr;itemNo: INTEGER); æDT HideDItem(theDialog,itemNo); æMM æRI HideDItem procedure IV-59 æC HideDItem hides the item numbered itemNo in the given dialog’s item list by giving the item a display rectangle that’s off the screen. (Specifically, if the left coordinate of the item’s display rectangle is less than 8192, ShowDItem adds 16384 to both the left and right coordinates the rectangle.) If the item is already hidden (that is, if the left coordinate is greater than 8192), HideDItem does nothing. HideDItem calls the EraseRect procedure on the item’s enclosing rectangle and adds the rectangle that contained the item (not necessarily the item’s display rectangle) to the update region. If the specified item is an active editText item, the item is first deactivated (by calling TEDeactivate). Note: If you have items that are close to each other, be aware that the Dialog Manager draws outside of the enclosing rectangle by 3 pixels for editText items and by 4 pixels for a default button. An item that’s been hidden by HideDItem can be redisplayed by the ShowDItem procedure. Note: To create a hidden item in a dialog item list, simply add 16384 to the left and right coordinates of the display rectangle. æKY InitDialogs æFp Dialogs.p æT PROCEDURE æTN $A97B æD PROCEDURE InitDialogs(resumeProc: ProcPtr); æDT InitDialogs(resumeProc); æRI InitDialogs procedure I-411, P-107, 112, 174 æC Call InitDialogs once before all other Dialog Manager routines, to initialize the Dialog Manager. InitDialogs does the following initialization: • It saves the pointer passed in resumeProc, if any, for access by the System Error Handler in case a fatal system error occurs. ResumeProc can be a pointer to a resume procedure, as described in the System Error Handler chapter, or NIL if no such procedure is desired. Assembly-language note: InitDialogs stores the address of the resume procedure in a global variable named ResumeProc. • It installs the standard sound procedure. • It passes empty strings to ParamText. æKY IsDialogEvent æFp Dialogs.p æT Function æTN $A97F æD FUNCTION IsDialogEvent(theEvent: EventRecord): BOOLEAN; æDT myVariable := IsDialogEvent(theEvent); æRI IsDialogEvent function I-416, N5-1, P-108, 175 æC If your application includes any modeless dialogs, call IsDialogEvent after calling the Toolbox Event Manager function GetNextEvent. Warning: If your modeless dialog contains any editText items, you must call IsDialogEvent (and then DialogSelect) even if GetNextEvent returns FALSE; otherwise your dialog won’t receive null events and the caret won’t blink. Pass the current event in theEvent. IsDialogEvent determines whether theEvent needs to be handled as part of a dialog. If theEvent is an activate or update event for a dialog window, a mouse-down event in the content region of an active dialog window, or any other type of event when a dialog window is active, IsDialogEvent returns TRUE; otherwise, it returns FALSE. When FALSE is returned, just handle the event yourself like any other event that’s not dialog-related. When TRUE is returned, you’ll generally end up passing the event to DialogSelect for it to handle (as described below), but first you should do some additional checking: • DialogSelect doesn’t handle keyboard equivalents of commands. Check whether the event is a key-down event with the Command key held down and, if so, carry out the command if it’s one that applies when a dialog window is active. (If the command doesn’t so apply, do nothing.) • In special cases, you may want to bypass DialogSelect or do some preprocessing before calling it. If so, check for those events and respond accordingly. You would need to do this, for example, if the dialog is to respond to disk-inserted events. For cases other than these, pass the event to DialogSelect for it to handle. æKY ModalDialog æFp Dialogs.p æT PROCEDURE æTN $A991 æD PROCEDURE ModalDialog(filterProc: ProcPtr;VAR itemHit: INTEGER); æDT ModalDialog(filterProc,itemHit); æMM æRT 34, 203 æRI ModalDialog procedure I-415, N34-2, 3, P-108, 176 æC Call ModalDialog after creating a modal dialog and bringing up its window in the frontmost plane. ModalDialog repeatedly gets and handles events in the dialog’s window; after handling an event involving an enabled dialog item, it returns with the item number in itemHit. Normally you’ll then do whatever is appropriate as a response to an event in that item. ModalDialog gets each event by calling the Toolbox Event Manager function GetNextEvent. If the event is a mouse-down event outside the content region of the dialog window, ModalDialog emits sound number 1 (which should be a single beep) and gets the next event; otherwise, it filters and handles the event as described below. Note: Once before getting each event, ModalDialog calls SystemTask, a Desk Manager procedure that must be called regularly so that desk accessories will work properly. The filterProc parameter determines how events are filtered. If it’s NIL, the standard filterProc function is executed; this causes ModalDialog to return 1 in itemHit if the Return key or Enter key is pressed. If filterProc isn’t NIL, ModalDialog filters events by executing the function it points to. Your filterProc function should have three parameters and return a Boolean value. For example, this is how it would be declared if it were named MyFilter: FUNCTION MyFilter (theDialog: DialogPtr; VAR theEvent: EventRecord; VAR itemHit: INTEGER) : BOOLEAN; A function result of FALSE tells ModalDialog to go ahead and handle the event, which either can be sent through unchanged or can be changed to simulate a different event. A function result of TRUE tells ModalDialog to return immediately rather than handle the event; in this case, the filterProc function sets itemHit to the item number that ModalDialog should return. Note: If you want it to be consistent with the standard filterProc function, your function should at least check whether the Return key or Enter key was pressed and, if so, return 1 in itemHit and a function result of TRUE. You can use the filterProc function, for example, to treat a typed character in a special way (such as ignore it, or make it have the same effect as another character or as clicking a button); in this case, the function would test for a key-down event with that character. As another example, suppose the dialog box contains a userItem whose procedure draws a clock with the current time displayed. The filterProc function can call that procedure and return FALSE without altering the current event. Note: ModalDialog calls GetNextEvent with a mask that excludes disk-inserted events. To receive disk-inserted events, your filterProc function can call GetNextEvent (or EventAvail) with a mask that accepts only that type of event. ModalDialog handles the events for which the filterProc function returns FALSE as follows: • In response to an activate or update event for the dialog window, ModalDialog activates or updates the window. • If the mouse button is pressed in an editText item, ModalDialog responds to the mouse activity as appropriate (displaying an insertion point or selecting text). If a key-down event occurs and there’s an editText item, text entry and editing are handled in the standard way for such items (except that if the Command key is down, ModalDialog responds as though it’s not). In either case, ModalDialog returns if the editText item is enabled or does nothing if it’s disabled. If a key-down event occurs when there’s no editText item, ModalDialog does nothing. • If the mouse button is pressed in a control, ModalDialog calls the Control Manager function TrackControl. If the mouse button is released inside the control and the control is enabled, ModalDialog returns; otherwise, it does nothing. • If the mouse button is pressed in any other enabled item in the dialog box, ModalDialog returns. If the mouse button is pressed in any other disabled item or in no item, or if any other event occurs, ModalDialog does nothing. æKY NewCDialog æFp Dialogs.p æT FUNCTION æTN $AA4B æD FUNCTION NewCDialog(dStorage: Ptr;boundsRect: Rect;title: Str255;visible: BOOLEAN; procID: INTEGER;behind: WindowPtr;goAwayFlag: BOOLEAN;refCon: LONGINT; items: Handle): DialogPtr; æDT myVariable := NewCDialog(dStorage,boundsRect,title,visible,procID,behind, goAwayFlag,refCon,items); æMM æRI NewCDialog function V-283 æC A new Dialog Manager routine has been added to support color dialogs: NewCDialog. Its parameters are identical to NewDialog, except that a cGrafPort is allocated through a NewCWindow call instead of a call to NewWindow. NewCDialog creates a dialog box as specified by its parameters and returns a cDialogPtr to the new dialog. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewCWindow, which creates the dialog window. The items parameter is a handle to the dialog’s item list. You can get the items handle by calling the Resource Manager to read the item list from the resource file into memory. After calling NewCDialog, you can use SetWinColor to add a color table to the dialog. This creates an auxiliary window record (auxWinRec) for the dialog window. You can access this record with the GetAuxWin routine. The dialogCItem handle within the auxWinRec points to the dialog item color table. If the dialog’s content color isn’t white, it’s a good idea to call NewCDialog with the visible flag set to FALSE. After the color table and color item list are installed, use ShowWindow to display the dialog if the dialog is the frontmost window. If the dialog is not in front, use ShowHide to display the dialog. æKY NewDialog æFp Dialogs.p æT FUNCTION æTN $A97D æD FUNCTION NewDialog(wStorage: Ptr;boundsRect: Rect;title: Str255;visible: BOOLEAN; procID: INTEGER;behind: WindowPtr;goAwayFlag: BOOLEAN;refCon: LONGINT; itmLstHndl: Handle): DialogPtr; æDT myVariable := NewDialog(wStorage,boundsRect,title,visible,procID,behind, goAwayFlag,refCon,itmLstHndl); æMM æRI NewDialog function I-412, P-107, 177 æC NewDialog creates a dialog as specified by its parameters and returns a pointer to the new dialog. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewWindow, which creates the dialog window; the meanings of these parameters are summarized below. The items parameter is a handle to the dialog’s item list. You can get the items handle by calling the Resource Manager to read the item list from the resource file into memory. Note: Advanced programmers can create their own item lists in memory rather than have them read from a resource file. The exact format is given later under “Formats of Resources for Dialogs and Alerts”. DStorage is analogous to the wStorage parameter of NewWindow; it’s a pointer to the storage to use for the dialog record. If you pass NIL for dStorage, the dialog record will be allocated in the heap (which, in the case of modeless dialogs, may cause the heap to become fragmented). BoundsRect, a rectangle given in global coordinates, determines the dialog window’s size and location. It becomes the portRect of the window’s grafPort. Remember that the top coordinate of this rectangle should be at least 25 points below the top of the screen for a modal dialog, to allow for the menu bar and the border around the portRect, and at least 40 points below the top of the screen for a modeless dialog, to allow for the menu bar and the window’s title bar. Title is the title of a modeless dialog box; pass the empty string for modal dialogs. If the visible parameter is TRUE, the dialog window is drawn on the screen. If it’s FALSE, the window is initially invisible and may later be shown with a call to the Window Manager procedure ShowWindow. Note: NewDialog generates an update event for the entire window contents, so the items aren’t drawn immediately, with the exception of controls. The Dialog Manager calls the Control Manager to draw controls, and the Control Manager draws them immediately rather than via the standard update mechanism. Because of this, the Dialog Manager calls the Window Manager procedure ValidRect for the enclosing rectangle of each control, so the controls won’t be drawn twice. If you find that the other items aren’t being drawn soon enough after the controls, try making the window invisible initially and then calling ShowWindow to show it. ProcID is the window definition ID, which leads to the window definition function for this type of window. The window definition IDs for the standard types of dialog window are dBoxProc for the modal type and documentProc for the modeless type. The behind parameter specifies the window behind which the dialog window is to be placed on the desktop. Pass POINTER(–1) to bring up the dialog window in front of all other windows. GoAwayFlag applies to modeless dialog boxes; if it’s TRUE, the dialog window has a close box in its title bar when the window is active. RefCon is the dialog window’s reference value, which the application may store into and access for any purpose. NewDialog sets the font of the dialog window’s grafPort to the system font or, if you previously called SetDAFont, to the specified font. It also sets the window class in the window record to dialogKind. æKY NoteAlert æFp Dialogs.p æT FUNCTION æTN $A987 æD FUNCTION NoteAlert(alertID: INTEGER;filterProc: ProcPtr): INTEGER; æDT myVariable := NoteAlert(alertID,filterProc); æMM æRI NoteAlert function I-420 æC NoteAlert is like StopAlert except that it draws the Note icon, which has the following resource ID: CONST noteIcon = 1; The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 'actb' with the same ID as the alert. æKY ok,cancel æFp Dialogs.p æC { Item numbers of OK and Cancel buttons } ok = 1; cancel = 2; æKY ParamText æFp Dialogs.p æT PROCEDURE æTN $A98B æD PROCEDURE ParamText(param0: Str255;param1: Str255;param2: Str255;param3: Str255); æDT ParamText(param0,param1,param2,param3); æMM æRI ParamText procedure I-421 æC ParamText provides a means of substituting text in statText items: param0 through param3 will replace the special strings '^0' through '^3' in all statText items in all subsequent dialog or alert boxes. Pass empty strings for parameters not used. Assembly-language note: Assembly-language programmers may pass NIL for parameters not used or for strings that are not to be changed. For example, if the text is defined as 'Cannot open document ^0' and docName is a string variable containing a document name that the user typed, you can call ParamText(docName,' ',' ',' ') Note: All strings that may need to be translated to other languages should be stored in resource files. Assembly-language note: The Dialog Manager stores handles to the four ParamText parameters in a global array named DAStrings. æKY ResetAlrtStage æFp Dialogs.p æT PROCEDURE æD PROCEDURE ResetAlrtStage; æDT ResetAlrtStage; æRI ResetAlrtStage procedure I-423 æC ResetAlrtStage resets the stage of the last occurrence of an alert so that the next occurrence of that same alert will be treated as its first stage. This is useful, for example, when you’ve used ParamText to change the text of an alert such that from the user’s point of view it’s a different alert. Assembly-language note: Assembly-language programmers can set the global variable ACount to –1 for the same effect. æKY SelIText æFp Dialogs.p æT PROCEDURE æTN $A97E æD PROCEDURE SelIText(theDialog: DialogPtr;itemNo: INTEGER;strtSel: INTEGER; endSel: INTEGER); æDT SelIText(theDialog,itemNo,strtSel,endSel); æMM æRI SelIText procedure I-422, P-110 æC Given a pointer to a dialog and the item number of an editText item in the dialog box, SelIText does the following: • If the item contains text, SelIText sets the selection range to extend from character position strtSel up to but not including character position endSel. The selection range is inverted unless strtSel equals endSel, in which case a blinking vertical bar is displayed to indicate an insertion point at that position. • If the item doesn’t contain text, SelIText simply displays the insertion point. For example, if the user makes an unacceptable entry in the editText item, the application can put up an alert box reporting the problem and then select the entire text of the item so it can be replaced by a new entry. (Without this procedure, the user would have to select the item before making the new entry.) Note: You can select the entire texxt by specifying 0 for strtSel and 32767 for endSel. For details about selection range and character position, see the TextEdit chapter. æKY SetDAFont æFp Dialogs.p æT PROCEDURE æD PROCEDURE SetDAFont(fontNum: INTEGER); æDT SetDAFont(fontNum); æRI SetDAFont procedure I-412 æC For subsequently created dialogs and alerts, SetDAFont causes the font of the dialog or alert window’s grafPort to be set to the font having the specified font number. If you don’t call this procedure, the system font is used. SetDAFont affects statText and editText items but not titles of controls, which are always in the system font. Assembly-language note: Assembly-language programmers can simply set the global variable DlgFont to the desired font number. æKY SetDItem æFp Dialogs.p æT PROCEDURE æTN $A98E æD PROCEDURE SetDItem(theDialog: DialogPtr;itemNo: INTEGER;itemType: INTEGER; item: Handle;box: Rect); æDT SetDItem(theDialog,itemNo,itemType,item,box); æMM æRT 34 æRI SetDItem procedure I-421, N34-1 æC SetDItem sets the item numbered itemNo in the given dialog’s item list, as specified by the parameters (without drawing the item). The itemType parameter is the item type; the item parameter is a handle to the item (or, for item type userItem, the procedure pointer); and the box parameter is the display rectangle for the item. Consider, for example, how to install an item of type userItem in a dialog: In the item list in the resource file, define an item in which the type is set to userItem and the display rectangle to (0,0)(0,0). Specify that the dialog window be invisible (in either the dialog template or the NewDialog call). After creating the dialog, coerce the item’s procedure pointer to type Handle; then call SetDItem, passing that handle and the display rectangle for the item. Finally, call the Window Manager procedure ShowWindow to display the dialog window. Note: Do not use SetDItem to change the text of a statText or editText item or to change or move a control. See the description of GetDItem above for more information. æKY SetIText æFp Dialogs.p æT PROCEDURE æTN $A98F æD PROCEDURE SetIText(item: Handle;text: Str255); æDT SetIText(item,text); æMM æRI SetIText procedure I-422 æC Given a handle to a statText or editText item in a dialog box, as returned by GetDItem, SetIText sets the text of the item to the specified text and draws the item. For example, suppose the exact content of a dialog’s text item cannot be determined until the application is running, but the display rectangle is defined in the resource file: Call GetDItem to get a handle to the item, and call SetIText with the desired text. æKY ShowDItem æFp Dialogs.p æT PROCEDURE æTN $A828 æD PROCEDURE ShowDItem(theDialog: DialogPtr;itemNo: INTEGER); æDT ShowDItem(theDialog,itemNo); æMM æRI ShowDItem procedure IV-59 æC ShowDItem redisplays the item numbered itemNo, previously hidden by HideDItem, by giving the item the display rectangle it had prior to the HideDItem call. (Specifically, if the left coordinate of the item’s display rectangle is greater than 8192, ShowDItem subtracts 16384 from both the left and right coordinates the rectangle.) If the item is already visible (that is, if the left coordinate is less than 8192), ShowDItem does nothing. ShowDItem adds the rectangle that contained the item (not necessarily the item’s display rectangle) to the update region so that it will be drawn. If the item becomes the only editText item, ShowDItem activates it (by calling TEActivate). æKY StageList æFp Dialogs.p æT PACKED RECORD æC StageList = PACKED RECORD boldItm4: 0..1; {default button item number - 1} boxDrwn4: BOOLEAN; {true if alert box to be drawn} sound4: 0..3; {sound number} boldItm3: 0..1; boxDrwn3: BOOLEAN; sound3: 0..3; boldItm2: 0..1; boxDrwn2: BOOLEAN; sound2: 0..3; boldItm1: 0..1; boxDrwn1: BOOLEAN; sound1: 0..3; END; »Alert Templates in Memory The data structure of an alert template is as follows: TYPE AlertTemplate = RECORD boundsRect: Rect; {becomes window's portRect} itemsID: INTEGER; {resource ID of item list} stages: StageList {alert stage information} END; BoundsRect is the rectangle that becomes the portRect of the window's grafPort. The itemsID field contains the resource ID of the item list for the alert. The information in the stages field determines exactly what should happen at each stage of the alert. It's packed into a word that has the following structure: TYPE StageList = PACKED RECORD boldItm4: 0..1; {default button item number minus 1} boxDrwn4: BOOLEAN; {TRUE if alert box to be drawn} sound4: 0..3 {sound number} boldItm3: 0..1; boxDrwn3: BOOLEAN; sound3: 0..3 boldItm2: 0..1; boxDrwn2: BOOLEAN; sound2: 0..3 boldItm1: 0..1; boxDrwn1: BOOLEAN; sound1: 0..3 END; Notice that the information is stored in reverse order—for the fourth stage first, and for the first stage last. The boldItm field indicates which button should be the default button (and therefore boldly outlined in the alert box). If the first two items in the alert’s item list are the OK button and the Cancel button, respectively, 0 will refer to the OK button and 1 to the Cancel button. The reason for this is that the value of boldItm plus 1 is interpreted as an item number, and normally items 1 and 2 are the OK and Cancel buttons, respectively. Whatever the item having the corresponding item number happens to be, a bold rounded-corner rectangle will be drawn outside its display rectangle. Note: When deciding where to place items in an alert box, be sure to allow room for any bold outlines that may be drawn. The boxDrwn field is TRUE if the alert box is to be drawn. The sound field specifies which sound should be emitted at this stage of the alert, with a number from 0 to 3 that’s passed to the current sound procedure. You can call ErrorSound to specify your own sound procedure; if you don’t, the standard sound procedure will be used (as described earlier in the “Alerts” section). You access the alert template by converting the handle returned by the Resource Manager to a template handle: TYPE AlertTHndl = ^AlertTPtr; AlertTPtr = ^AlertTemplate; Assembly-language note: Rather than offsets into the fields of the StageList data structure, there are masks for accessing the information stored for an alert stage in a stages word; they’re listed in the summary at the end of this chapter. æKY StopAlert æFp Dialogs.p æT FUNCTION æTN $A986 æD FUNCTION StopAlert(alertID: INTEGER;filterProc: ProcPtr): INTEGER; æDT myVariable := StopAlert(alertID,filterProc); æMM æRI StopAlert function I-419, V-284, P-109, 182 æC StopAlert is the same as the Alert function (above) except that before drawing the items of the alert in the alert box, it draws the Stop icon in the top left corner of the box (within the rectangle (10,20)(42,52)). The Stop icon has the following resource ID: CONST stopIcon = 0; If the application’s resource file doesn’t include an icon with that ID number, the Dialog Manager uses the standard Stop icon in the system resource file (see Figure 11). The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 'actb' with the same ID as the alert. •••Refer to Figure 11.••• Figure 11–Standard Alert Icons æKY stopIcon,noteIcon,cautionIcon æFp Dialogs.p æC { Resource IDs of alert icons } stopIcon = 0; noteIcon = 1; cautionIcon = 2; æKY UpdtDialog æFp Dialogs.p æT PROCEDURE æTN $A978 æD PROCEDURE UpdtDialog(theDialog: DialogPtr;updateRgn: RgnHandle); æDT UpdtDialog(theDialog,updateRgn); æMM æRI UpdtDialog procedure IV-60 æC UpdtDialog is a faster version of the DrawDialog procedure. Instead of drawing the entire contents of the given dialog box, UpdtDialog draws only the items that are in a specified update region. UpdtDialog is called in response to an update event, and is usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port. (For more details, see the BeginUpdate procedure in the Window Manager chapter.) æKY DisAsmLookup.p æKL Disassembler endOfModule InitLookup Lookup LookupTrapName ModifyOperand showMacsBugSymbol validMacsBugSymbol DisAsmStr80 LookupRegs _A0_ _A1_ _A2_ _A3_ _A4_ _A5_ _A6_ _A7_ _ABS_ _PC_ _TRAP_ æKY DisAsmStr80 æFp DisAsmLookup.p æT TYPE æC DisAsmStr80 = String[80]; æKY Disassembler æFp DisAsmLookup.p æT PROCEDURE æD PROCEDURE Disassembler(DstAdjust: LONGINT;VAR BytesUsed: INTEGER;FirstByte: UNIV Ptr; VAR Opcode: UNIV DisAsmStr80;VAR Operand: UNIV DisAsmStr80;VAR Comment: UNIV DisAsmStr80; LookUpProc: UNIV Ptr); æDT Disassembler(DstAdjust,BytesUsed,FirstByte,Opcode,Operand,Comment,LookUpProc); æC (* Disassembler is a Pascal routine to be called to disassemble a sequence of bytes. All MC68xxx, MC68881, and MC68851 instructions are supported. The sequence of bytes to be disassembled are pointed to by FirstByte. BytesUsed bytes starting at FirstByte are consumed by the disassembly, and the Opcode, Operand, and Comment strings returned as NULL TERMINATED Pascal strings (for easier manipulation with C). The caller is then free to format or use the output strings any way appropriate to the application. Depending on the opcode and effective address(s) (EA's) to be disassembled, the Opcode, Operand, and Comment strings contain the following information: Case Opcode Operand Comment ======================================================================= Non PC-relative EA's op.sz EA's PC-relative EA's op.sz EA's ; address Toolbox traps DC.W $AXXX ; TB XXXX OS traps DC.W $AXXX ; OS XXXX Invalid bytes DC.W $XXXX ; ???? Invalid byte #immediate DC.W $XXXX,... ; op.sz #$??XX,EA ======================================================================= For valid disassembly of processor instructions the appropriate MC68XXX opcode mnemonic is generated for the Opcode string along with a size attribute when required. The source and destination EA's are generated as the Operand along with a possible comment. Comments start with a ';'. Traps use a DC.W assembler directive as the Opcode with the trap word as the Operand and a comment indicating whether the trap is a toolbox or OS trap and what the trap number is. As described later the caller can generate symbolic substitutions into EA's and provide names for traps. Invalid instructions cause the string 'DC.W' to be returned in the Opcode string. Operand is '$XXXX' (the invalid word) with a comment of '; ????'. BytesUsed is 2. This is similar to the trap call case except for the comment. A special case is made for immediate byte operands with a nonzero high order byte. For example, the bytes $020011FF, when actually executed, would be interpreted as ANDI.B $FF,D0. The processor will IGNORE the high order byte of the immediate data! Thus, the bytes may be considered as valid. Since the Disassembler has no way of knowing the context in which it is disassembling, it returns the Opcode as 'DC.W' as in the normal invalid case. However, the Operand string shows ALL the words disassembled separated with commas and places the possibly valid disassembly in the Operand's comment indicating the nonzero bytes. Thus for the example $020011FF bytes, the Opcode will be 'DC.W', the Operand will be '$0200,$11FF', and the Comment '; ANDI.B #$??FF,D0'. BytesUsed in this case would be 4. Note, the Operand EA's is syntatically similar to but NOT COMPATIBLE with the MPW assembler! This is because the Disassembler generates byte hex constants as "$XX" and word hex constants as "$XXXX". Negative values (e.g., $FF or $FFFF) produced by the Disassembler are treated as long word values by the MPW assembler. Thus it is assumed that Disassembler output will NOT be used as MPW assembler input. If that is the goal, then the caller must convert strings of the form $XX or $XXXX in the Operand string to their decimal equivalent. The routine ModifyOperand is provided in this unit to aid with the conversion process. Since a PC-relative comment is an address, the only address that the Disassembler knows about is the address of the code pointed to by FirstByte. Generally, that may be a buffer that has no relation to "reality", i.e., the actual code loaded into the buffer. Therefore, to allow the address comment to be mapped back to some actual address the caller may specify an adjustment factor, specified by DstAdjust that is ADDED to the value that normally would be placed in the comment. Operand effective address strings are generated as a function of the effective address mode and a special case is made for A-trap opcode strings. In places where a possible symbolic reference could be substituted for an address (or a portion of an address), the Disassembler can call a user specified routine to do the substitution (using th LookupProc parameter described later). The following table summarizes the generated effective addresses and where symbolic substitutions (S) can be made: Mode Generated Effective Address Effective Address with Substitution ======================================================================== 0 Dn Dn 1 An An 2 (An) (An) 3 (An)+ (An)+ 4 -(An) -(An) 5 ∂(An) S(An) or just S (if An=A5, ∂≥0) 6n ∂(An,Xn.Size*Scale) S(An,Xn.Size*Scale) 6n (BD,An,Xn.Size*Scale) (S,An,Xn.Size*Scale) 6n ([BD,An],Xm.Size*Scale,OD) ([S,An],Xm.Size*Scale,OD) 6n ([BD,An,Xn.Size*Scale],OD) ([S,An,Xn.Size*Scale],OD) 70 ∂ S 71 ∂ S 72 *±∂ S 73 *±∂(Xn.Size*Scale) S(Xn.Size*Scale) 73 (*±∂,Xn.Size*Scale) (S,Xn.Size*Scale) 73 ([*±∂],Xm.Size*Scale,OD) ([S],Xm.Size*Scale,OD) 73 ([*±∂,Xn.Size*Scale],OD) ([S,Xn.Size*Scale],OD) 74 #data #data ======================================================================== For A-traps, the substitution can be performed to substitute for the DC.W opcode string. If the substitution is made then the Disassembler will generate ,Sys and/or ,Immed flags as operands for Toolbox traps and ,AutoPop for OS traps when the bits in the trap word indicates these settings. | Generated | Substituted | Opcode Operand Comment | Opcode Operand Comment ======================================================================== Toolbox | DC.W $AXXX ; TB XXXX | S [,Sys][,Immed] ; AXXX OS | DC.W $AXXX ; OS XXXX | S [,AutoPop] ; AXXX ======================================================================== All displacements (∂, BD, OD) are hexadecimal values shown as a byte ($XX), word ($XXXX), or long ($XXXXXXXX) as appropriate. The *Scale is suppressed if 1. The Size is W or L. Note that effective address substitutions can only be made for "∂(An)", "BD,An", and "*±∂" cases. For all the effective address modes 5, 6n, 7n, and for A-traps, a coroutine (a procedure) whose address is specified by the LookupProc parameter is called by the Disassembler (if LookupProc is not NIL) to do the substitution (or A-trap comment) with a string returned by the proc. It is assumed that the proc pointed to by LookupProc is a level 1 Pascal proc declared as follows: PROCEDURE Lookup( PC: UNIV Ptr; {Addr of extension/trap word} BaseReg: LookupRegs; {Base register/lookup mode } Opnd: UNIV LongInt; {Trap word, PC addr, disp. } VAR S: DisAsmStr80); {Returned substitution } where TYPE DisAsmStr80 = String[80]; or in C, pascal void LookUp(Ptr PC, LookupRegs BaseReg, long Opnd, char *S); PC = Pointer to instruction extension word or A-trap word in the buffer pointed to by the Disassembler's FirstByte parameter. BaseReg = This determines the meaning of the Opnd value and supplies the base register for the "∂(An)", "BD,An", and "*±∂" cases. BaseReg may contain any one of the following values: _A0_ = 0 ==> A0 _A1_ = 1 ==> A1 _A2_ = 2 ==> A2 _A3_ = 3 ==> A3 _A4_ = 4 ==> A4 _A5_ = 5 ==> A5 _A6_ = 6 ==> A6 _A7_ = 7 ==> A7 _PC_ = 8 ==> PC-relative (special case) _ABS_ = 9 ==> Abs addr (special case) _TRAP_ = 10 ==> Trap word (special case) For absolute addressing (modes 70 and 71), BaseReg contains _ABS_. For A-traps, BaseReg would contain _TRAP_. Opnd = The contents of this LongInt is determined by the BaseReg parameter just described. For BaseReg = _TRAP_ (A-traps): Opnd is the entire trap word. The high order 16 bits of Opnd are zero. For BaseReg = _ABS_ (absolute effective address): Opnd contains the (extended) 32-bit address specifed by the instruction's effective address. Such addresses would generally be used to reference low memory globals on a Macintosh. For BaseReg = _PC_ (PC-relative effective address): Opnd contains the 32-bit address represented by "*±∂" adjusted by the Disassembler's DstAdjust parameter. For BaseReg = _An_ (effective address with a base register): Opnd contains the (sign-extended) 32-bit (base) displacement from the instruction's effective address. In the Macintosh environment, a BaseReg specifying A5 implies either global data references or Jump Table references. Positive Opnd values with an A5 BaseReg thus mean Jump Table references, while a negative offset would mean a global data reference. Base registers of A6 or A7 would usually mean local data. S = Pascal string returned from Lookup containing the effective address substitution string or a trap name for A-traps. S is set to null PRIOR to calling Lookup. If it is still null on return, the string is not used. If not null, then for A-traps, the returned string is used as a opcode string. In all other cases the string is substituted as shown in the above table. Depending on the application, the caller has three choices on how to use the Disassembler and an associated Lookup proc: (1). The caller can call just the Disassembler and provide his own Lookup proc. In that case the calling conventions discussed above must be followed. (2). The caller can provide NIL for the LookupProc parameter, in which case, NO Lookup proc will be called. (3). The caller can call first InitLookup (described below, a proc provided with this unit) and pass the address of this unit's standard Lookup proc when Disassembler is called. In this case all the control logic to determine the kind of substitution to be done is provided for the caller and all that need to be provided by the user are routines to look up any or all of the following: • PC-relative references • Jump Table references • Absolute address references • Trap names • References with offsets from base registers *) æKY endOfModule æFp DisAsmLookup.p æT FUNCTION æD FUNCTION endOfModule(address: UNIV Ptr;limit: UNIV Ptr;symbol: StringPtr; VAR nextModule: UNIV Ptr): StringPtr; C; æDT myVariable := endOfModule(address,limit,symbol,nextModule); æC { Check to see if the specified memory address contains a RTS, JMP (A0) or RTD #n instruction immediately followed by a valid MacsBug symbol. These sequences are the only ones which can determine an end of module when MacsBug symbols are present. During the check, the instruction and its following MacsBug symbol must be fully contained in the bytes starting at the specified address parameter, up to, but not including, the byte pointed to by the limit parameter. If the end of module is NOT found, then NULL is returned as the function's result. However, if a end of module is found, the MacsBug symbol is returned in symbol (if it is not NULL) as a null terminated Pascal string (with trailing blanks removed), and the functions returns the pointer to the start of the MacsBug symbol (i.e., address+2 for RTS or JMP (A0) and address+4 for RTD #n). This address may then be used as in input parameter to showMacsBugSymbol to convert the MacsBug symbol to a Disassembler operand string. Also returned in nextModule is where we think the FOLLOWING module begins. In the "old style" cases (see validMacsBugSymbol) this will always be 8 or 16 bytes after the input address. For new style the Apple Pascal and C cases this will depend on the symbol length, existence of a pad byte, and size of the constant (literal) area. See validMacsBugSymbol for a description of valid MacsBug symbol formats. } æKY InitLookup æFp DisAsmLookup.p æT PROCEDURE æD PROCEDURE InitLookup(PCRelProc: UNIV Ptr;JTOffProc: UNIV Ptr;TrapProc: UNIV Ptr; AbsAddrProc: UNIV Ptr;IdProc: UNIV Ptr); æDT InitLookup(PCRelProc,JTOffProc,TrapProc,AbsAddrProc,IdProc); æC { Prepare for use of this unit's Lookup proc. When Disassembler is called and the address of this unit's Lookup proc is specified, then for PC-relative, Jump Table references, A-traps, absolute addresses, and offsets from a base register, the associated level 1 Pascal proc specified here is called (if not NULL -- all five addresses are preset to NULL). The calls assume the following declarations for these procs (see Lookup, below for further details): PROCEDURE PCRelProc(Address: UNIV LongInt; VAR S: UNIV DisAsmStr80); PROCEDURE JTOffProc(A5JTOffset: UNIV Integer; VAR S: UNIV DisAsmStr80); PROCEDURE TrapNameProc(TrapWord: UNIV Integer; VAR S: UNIV DisAsmStr80); PROCEDURE AbsAddrProc(AbsAddr: UNIV LongInt; VAR S: UNIV DisAsmStr80); PROCEDURE IdProc(BaseReg: LookupRegs; Offset: UNIV LongInt; VAR S: UNIV DisAsmStr80); or in C, pascal void PCRelProc(long Address, char *S) pascal void JTOffProc(short A5JTOffset, char *S) pascal void TrapNameProc(unsigned short TrapWord, char *S) pascal void AbsAddrProc(long AbsAddr, char *S) pascal void IdProc(LookupRegs BaseReg, long Offset, char *S) Note: InitLookup contains initialized data which requires initializing at load time (this is of concern only to users with assembler main programs. } æKY Lookup æFp DisAsmLookup.p æT PROCEDURE æD PROCEDURE Lookup(PC: UNIV Ptr;BaseReg: LookupRegs;Opnd: UNIV LongInt; VAR S: DisAsmStr80); æDT Lookup(PC,BaseReg,Opnd,S); æC { This is a standard Lookup proc available to the caller for calls to the Disassembler. If the caller elects to use this proc, then InitLookup MUST be called prior to any calls to the Disassembler. All the logic to determine the type of lookup is done by this proc. For PC-relative, Jump Table references, A-traps, absolute addresses, and offsets from a base register, the associated level 1 Pascal proc specified in the InitLookup call (if not NULL) is called. This scheme simplifies the Lookup mechanism by allowing the caller to deal with just the problems related to the application. } æKY LookupRegs,_A0_,_A1_,_A2_,_A3_,_A4_,_A5_,_A6_,_A7_,_PC_,_ABS_,_TRAP_ æFp DisAsmLookup.p æC LookupRegs = (_A0_,_A1_,_A2_,_A3_,_A4_,_A5_,_A6_,_A7_,_PC_,_ABS_,_TRAP_); æKY LookupTrapName æFp DisAsmLookup.p æT PROCEDURE æD PROCEDURE LookupTrapName(TrapWord: UNIV Integer;VAR S: UNIV DisAsmStr80); æDT LookupTrapName(TrapWord,S); æC { This is a procedure provided to allow conversion of a trap instruction (in TrapWord) to its corresponding trap name (in S). It is provided primarily for use with the Disassembler and its address may be passed to InitLookup above for use by this unit's Lookup routine. Alternatively, there is nothing prohibiting the caller from using it directly for other purposes or by some other lookup proc. Note: The tables in this proc make the size of this proc about 9500 bytes. The trap names are fully spelled out in upper and lower case. } æKY ModifyOperand æFp DisAsmLookup.p æT PROCEDURE æD PROCEDURE ModifyOperand(VAR Operand: UNIV DisAsmStr80); æDT ModifyOperand(Operand); æC { Scan an operand string, i.e., the null terminated Pascal string returned by the Disassembler (null MUST be present here) and modify negative hex values to negated positive value. For example, $FFFF(A5) would be modified to -$0001(A5). The operand to be processed is passed as the function's parameter which is edited "in place" and returned to the caller. This routine is essentially a pattern matcher and attempts to only modify 2, 4, and 8 digit hex strings in the operand that "might" be offsets from a base register. If the matching tests are passed, the same number of original digits are output (because that indicates a value's size -- byte, word, or long). For a hex string to be modified, the following tests must be passed: • There must have been exactly 2, 4, or 8 digits. Only hex strings $XX, $XXXX, and $XXXXXXXX are possible candidates because that is the only way the Disassembler generates offsets. • Hex string must be delimited by a "(" or a ",". The "(" allows offsets for $XXXX(An,...) and $XX(An,Xn) addressing modes. The comma allows for the MC68020 addressing forms. • The "$X..." must NOT be preceded by a "±". This eliminates the possibility of modifying the offset of a PC-relative addressing mode always generated in the form "*±$XXXX". • The "$X..." must NOT be preceded by a "#". This eliminates modifying immediate data. • Value must be negative. Negative values are the only values we modify. A value $FFFF is modified to -$0001. } æKY showMacsBugSymbol æFp DisAsmLookup.p æT FUNCTION æD FUNCTION showMacsBugSymbol(symStart: UNIV Ptr;limit: UNIV Ptr;operand: StringPtr; VAR bytesUsed: INTEGER): StringPtr; C; æDT myVariable := showMacsBugSymbol(symStart,limit,operand,bytesUsed); æC { Format a MacsBug symbol as a operand of a DC.B directive. The first one or two bytes of the symbol are generated as $80+'c' if they have there high high bits set. All other characters are shown as characters in a string constant. The pad byte, if present, is one is also shown as $00. This routine is called to check that the bytes pointed to by symStart represent a valid MacsBug symbol. The symbol must be fully contained in the bytes starting at symStart, up to, but not including the byte pointed to by the limit parameter. When called, showMacsBugSymbol assumes that symStart is pointing at a valid MacsBug symbol as validated by the validMacsBugSymbol or endOfModule routines. As with validMacsBugSymbol, the symbol must be fully contained in the bytes starting at symStart up to, but not including, the byte pointed to by the end parameter. The string is returned in the 'operand' parameter as a null terminated Pascal string. The function also returns a pointer to this string as its return value (NULL is returned only if the byte pointed to by the limit parameter is reached prior to processing the entire symbol -- which should not happen if properly validated). The number of bytes used for the symbol is returned in bytesUsed. Due to the way MacsBug symbols are encoded, bytesUsed may not necessarily be the same as the length of the operand string. A valid MacsBug symbol consists of the characters '_', '%', spaces, digits, and upper/lower case letters in a format determined by the first two bytes of the symbol as described in the validMacsBugSymbol routine. } æKY validMacsBugSymbol æFp DisAsmLookup.p æT FUNCTION æD FUNCTION validMacsBugSymbol(symStart: UNIV Ptr;limit: UNIV Ptr;symbol: StringPtr): StringPtr; C; æDT myVariable := validMacsBugSymbol(symStart,limit,symbol); æC { Check that the bytes pointed to by symStart represents a valid MacsBug symbol. The symbol must be fully contained in the bytes starting at symStart, up to, but not including, the byte pointed to by the limit parameter. If a valid symbol is NOT found, then NULL is returned as the function's result. However, if a valid symbol is found, it is copied to symbol (if it is not NULL) as a null terminated Pascal string, and return a pointer to where we think the FOLLOWING module begins. In the "old style" cases (see below) this will always be 8 or 16 bytes after the input symStart. For new style Apple Pascal and C cases this will depend on the symbol length, existence of a pad byte, and size of the constant (literal) area. In all cases, trailing blanks are removed from the symbol. A valid MacsBug symbol consists of the characters '_', '%', spaces, digits, and upper/lower case letters in a format determined by the first two bytes of the symbol as follows: 1st byte | 2nd byte | Byte | Range | Range | Length | Comments ============================================================================== $20 - $7F | $20 - $7F | 8 | "Old style" MacsBug symbol format $A0 - $FF | $20 - $7F | 8 | "Old style" MacsBug symbol format ------------------------------------------------------------------------------ $20 - $7F | $80 - $FF | 16 | "Old style" MacApp symbol ab==>b.a $A0 - $FF | $80 - $FF | 16 | "Old style" MacApp symbol ab==>b.a ------------------------------------------------------------------------------ $80 | $01 - $FF | n | n = 2nd byte (Apple Compiler symbol) $81 - $9F | $00 - $FF | m | m = 1st byte & $7F (Apple Compiler symbol) ============================================================================== The formats are determined by whether bit 7 is set in the first and second bytes. This bit will removed when we find it or'ed into the first and/or second valid symbol characters. The first two formats in the above table are the basic "old style" (pre- existing) MacsBug formats. The first byte may or may not have bit 7 set the second byte is a valid symbol character. The first byte (with bit 7 removed) and the next 7 bytes are assumed to comprise the symbol. The second pair of formats are also "old style" formats, but used for MacApp symbols. Bit 7 set in the second character indicates these formats. The symbol is assumed to be 16 bytes with the second 8 bytes preceding the first 8 bytes in the generated symbol. For example, 12345678abcdefgh represents the symbol abcdefgh.12345678. The last pair of formats are reserved by Apple and generated by the MPW Pascal and C compilers. In these cases the value of the first byte is always between $80 and $9F, or with bit 7 removed, between $00 and $1F. For $00, the second byte is the length of the symbol with that many bytes following the second byte (thus a max length of 255). Values $01 to $1F represent the length itself. A pad byte may follow these variable length cases if the symbol does not end on a word boundary. Following the symbol and the possible pad byte is a word containing the size of the constants (literals) generated by the compiler. Note that if symStart actually does point to a valid MacsBug symbol, then you may use showMacsBugSymbol to convert the MacsBug symbol bytes to a string that could be used as a DC.B operand for disassembly purposes. This string explicitly shows the MacsBug symbol encodings. } æKY DiskInit.p æKL DIBadMount DIFormat DILoad DIUnload DIVerify DIZero HFSDefaults æKY DIBadMount æFp DiskInit.p æT FUNCTION æTN $A9E9 æD FUNCTION DIBadMount(where: Point;evtMessage: LONGINT): INTEGER; æDT myVariable := DIBadMount(where,evtMessage); æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 Call DIBadMount when a disk-inserted event occurs if the result code in the high-order word of the associated event message indicates an error (that is, the result code is other than noErr). Given the event message in evtMessage, DIBadMount evaluates the result code and either ejects the disk or lets the user initialize and name it. The low-order word of the event message contains the drive number. The where parameter specifies the location (in global coordinates) of the top left corner of the dialog box displayed by DIBadMount. If the result code passed is extFSErr, memFullErr, nsDrvErr, paramErr, or volOnLinErr, DIBadMount simply ejects the disk from the drive and returns the result code. If the result code ioErr, badMDBErr, or noMacDskErr is passed, the error can be corrected by initializing the disk; DIBadMount displays a dialog box that describes the problem and asks whether the user wants to initialize the disk. For the result code ioErr, the dialog box shown in Figure 1 is displayed. (This happens if the disk is brand new.) For badMDBErr and noMacDskErr, DIBadMount displays a similar dialog box in which the description of the problem is “This disk is damaged” and “This is not a Macintosh disk”, respectively. •••Refer to Figure 1.••• Figure 1–Disk Initialization Dialog for IOErr Note: Before presenting the disk initialization dialog, DIBadMount checks whether the drive contains an already mounted volume; if so, it ejects the disk and returns 2 as its result. This will happen rarely and may reflect an error in your program (for example, you forgot to call DILoad and the user had to switch to the disk containing the system resource file). If the user responds to the disk initialization dialog by clicking the Eject button, DIBadMount ejects the disk and returns 1 as its result. If the Initialize button is clicked, a box displaying the message “Initializing disk...” appears, and DIBadMount attempts to initialize the disk. If initialization fails, the disk is ejected and the user is informed as shown in Figure 2; after the user clicks OK, DIBadMount returns a negative result code ranging from firstDskErr to lastDskErr, indicating that a low-level disk error occurred. •••Refer to Figure 2.••• Figure 2–Initialization Failure Dialog If the disk is successfully initialized, the dialog box in Figure 3 appears. After the user names the disk and clicks OK, DIBadMount mounts the volume by calling the File Manager function MountVol and returns MountVol’s result code (noErr if no error occurs). •••Refer to Figure 3.••• Figure 3–Dialog for Naming a Disk Result codes noErr No error extFSErr External file system memFullErr Not enough room in heap zone nsDrvErr No such drive paramErr Bad drive number volOnLinErr Volume already on-line firstDskErr Low-level disk error through lastDskErr Other results 1 User clicked Eject 2 Mounted volume in drive æKY DIFormat æFp DiskInit.p æT FUNCTION æTN $A9E9 æD FUNCTION DIFormat(drvNum: INTEGER): OSErr; æDT myVariable := DIFormat(drvNum); æMM æRI DIFormat function II-398 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DIFormat formats the disk in the drive specified by the given drive number and returns a result code indicating whether the formatting was completed successfully or failed. Formatting a disk consists of writing special information onto it so that the Disk Driver can read from and write to the disk. Result codes noErr No error firstDskErr Low-level disk error through lastDskErr æKY DILoad æFp DiskInit.p æT PROCEDURE æTN $A9E9 æD PROCEDURE DILoad; æDT DILoad; æMM æRI DILoad procedure II-396 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DILoad reads the Disk Initialization Package, and its associated dialog and dialog items, from the system resource file into memory and makes them unpurgeable. Note: DIFormat, DIVerify, and DIZero don’t need the dialog, so if you use only these routines you can call the Resource Manager function GetResource to read just the package resource into memory (and the Memory Manager procedure HNoPurge to make it unpurgeable). æKY DIUnload æFp DiskInit.p æT PROCEDURE æTN $A9E9 æD PROCEDURE DIUnload; æDT DIUnload; æMM æRI DIUnload procedure II-396 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DIUnload makes the Disk Initialization Package (and its associated dialog and dialog items) purgeable. æKY DIVerify æFp DiskInit.p æT FUNCTION æTN $A9E9 æD FUNCTION DIVerify(drvNum: INTEGER): OSErr; æDT myVariable := DIVerify(drvNum); æMM æRI DIVerify function II-398 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 DIVerify verifies the format of the disk in the drive specified by the given drive number; it reads each bit from the disk and returns a result code indicating whether all bits were read successfully or not. DIVerify doesn’t affect the contents of the disk itself. Result codes noErr No error firstDskErr Low-level disk error through lastDskErr æKY DIZero æFp DiskInit.p æT FUNCTION æTN $A9E9 æD FUNCTION DIZero(drvNum: INTEGER;volName: Str255): OSErr; æDT myVariable := DIZero(drvNum,volName); æMM æRT 70 æRI DIZero function II-399, N70-2 æC Assembly-language note: The trap macro for the Disk Initialization Package is _Pack2. The routine selectors are as follows: diBadMount .EQU 0 diLoad .EQU 2 diUnload .EQU 4 diFormat .EQU 6 diVerify .EQU 8 diZero .EQU 10 On the unmounted volume in the drive specified by the given drive number, DIZero writes the volume information, a block map, and a file directory as for a volume with no files; the volName parameter specifies the volume name to be included in the volume information. This is the last step in initialization (after formatting and verifying) and makes any files that are already on the volume permanently inaccessible. If the operation fails, DIZero returns a result code indicating that a low-level disk error occurred; otherwise, it mounts the volume by calling the File Manager function MountVol and returns MountVol’s result code (noErr if no error occurs). Result codes noErr No error badMDBErr Bad master directory block extFSErr External file system ioErr I/O error memFullErr Not enough room in heap zone noMacDskErr Not a Macintosh disk nsDrvErr No such drive paramErr Bad drive number volOnLinErr Volume already on-line firstDskErr Low-level disk error through lastDskErr æKY HFSDefaults æFp DiskInit.p æT RECORD æC HFSDefaults = RECORD sigWord: PACKED ARRAY [0..1] OF Byte; { signature word} abSize: LONGINT; { allocation block size in bytes} clpSize: LONGINT; { clump size in bytes} nxFreeFN: LONGINT; { next free file number} btClpSize: LONGINT; { B-Tree clump size in bytes} rsrv1: INTEGER; { reserved} rsrv2: INTEGER; { reserved} rsrv3: INTEGER; { reserved} END; »Formatting Hierarchical Volumes The Disk Initialization Package must set certain volume characteristics when placing a hierarchical file directory on a volume. Default values for these volume characteristics are stored in the 128K ROM; this section is for advanced programmers who want to substitute their own values. The record containing the default values, if defined in Pascal, would look like this: TYPE HFSDefaults = PACKED RECORD sigWord: ARRAY[1..2] OF CHAR; {signature word} abSize: LONGINT; {allocation block size in bytes} clpSize: LONGINT; {clump size in bytes} nxFreeFN: LONGINT; {next free file number} btClpSize: LONGINT; {B*-Tree clump size in bytes} rsrv1: INTEGER; {reserved} rsrv2: INTEGER; {reserved} rsrv3: INTEGER; {reserved} END; The default values for these fields are as follows: Field Default value sigWord 'BD' abSize 0 clpSize 4 * abSize nxFreeFN 16 btClpSize 0 To supply your own values for these fields, create a similar, nonrelocatable record containing the desired values and place a pointer to it in the global variable FmtDefaults. To restore the system defaults, simply clear FmtDefaults. The sigWord must equal 'BD' (meaning “big disk”) for the volume to be recognized as a hierarchical volume. If the specified allocation block size is 0, the allocation block size is calculated according to the size of the volume: abSize = (1 + (volSize in blocks / 64K)) * 512 bytes If the specified B*-tree clump size is 0, the clump size for both the catalog and extent trees is calculated according to the size of the volume: btClpSize = (volSize in blocks)/128 * 512bytes æKY Disks.p æKL DiskEject DriveStatus SetTagBuffer DrvSts æKY DiskEject æFp Disks.p æT FUNCTION æD FUNCTION DiskEject(drvNum: INTEGER): OSErr; æDT myVariable := DiskEject(drvNum); æMM æRI DiskEject function II-214 æC [Not in ROM] Assembly-language note: DiskEject is equivalent to a Control call with csCode equal to the global constant ejectCode. DiskEject ejects the disk from the internal drive if drvNum is 1, or from the external drive if drvNum is 2. Result codes noErr No error nsDrvErr No such drive æKY DriveStatus æFp Disks.p æT FUNCTION æD FUNCTION DriveStatus(drvNum: INTEGER;VAR status: DrvSts): OSErr; æDT myVariable := DriveStatus(drvNum,status); æMM æRI DriveStatus function II-215 æC [Not in ROM] Assembly-language note: DriveStatus is equivalent to a Status call with csCode equal to the global constant drvStsCode; status is returned in csParam through csParam+21. DriveStatus returns information about the internal drive if drvNum is 1, or about the external drive if drvNum is 2. The information is returned in a record of type DrvSts: TYPE DrvSts = RECORD track: INTEGER; {current track} writeProt: SignedByte; {bit 7=1 if volume is locked} diskInPlace: SignedByte; {disk in place} installed: SignedByte; {drive installed} sides: SignedByte; {bit 7=0 if single-side drive} qLink: QElemPtr; {next queue entry} qType: INTEGER; {reserved for future use} dQDrive: INTEGER; {drive number} dQRefNum: INTEGER; {driver reference number} dQFSID: INTEGER; {file-system identifier} twoSideFmt: SignedByte; {-1 if two-sided disk} needsFlush: SignedByte; {reserved for future use} diskErrs: INTEGER {error count} END; The diskInPlace field is 0 if there’s no disk in the drive, 1 or 2 if there is a disk in the drive, or –4 to –1 if the disk was ejected in the last 1.5 seconds. The installed field is 1 if the drive is connected to the Macintosh, 0 if the drive might be connected to the Macintosh, and –1 if the drive isn’t installed. The value of twoSideFmt is valid only when diskInPlace=2. The value of diskErrs is incremented every time an error occurs internally within the Disk Driver. Result codes noErr No error nsDrvErr No such drive æKY DrvSts æFp Disks.p æT RECORD æC DrvSts = RECORD track: INTEGER; {current track} writeProt: SignedByte; {bit 7 = 1 if volume is locked} diskInPlace: SignedByte; {disk in drive} installed: SignedByte; {drive installed} sides: SignedByte; {-1 for 2-sided, 0 for 1-sided} driveQLink: QElemPtr; {next queue entry} driveQVers: INTEGER; {1 for HD20} dQDrive: INTEGER; {drive number} dQRefNum: INTEGER; {driver reference number} dQFSID: INTEGER; {file system ID} CASE DriveKind OF sony: (twoSideFmt: SignedByte; {after 1st rd/wrt: 0=1 side, -1=2 side} needsFlush: SignedByte; {-1 for MacPlus drive} diskErrs: INTEGER); {soft error count} hard20: (driveSize: INTEGER; {drive block size low word} driveS1: INTEGER; {drive block size high word} driveType: INTEGER; {1 for HD20} driveManf: INTEGER; {1 for Apple Computer, Inc.} driveChar: SignedByte; {230 ($E6) for HD20} driveMisc: SignedByte); {0 -- reserved} END; æKY SetTagBuffer æFp Disks.p æT FUNCTION æD FUNCTION SetTagBuffer(buffPtr: Ptr): OSErr; æDT myVariable := SetTagBuffer(buffPtr); æMM æRI SetTagBuffer function II-214 æC [Not in ROM] Assembly-language note: SetTagBuffer is equivalent to a Control call with csCode equal to the global constant tgBuffCode. An application can change the information used in the file tags buffer by calling SetTagBuffer. The buffPtr parameter points to a buffer that contains the information to be used. If buffPtr is NIL, the information in the file tags buffer isn’t changed. If buffPtr isn’t NIL, every time the Disk Driver reads a sector from the disk, it stores the file tags in the file tags buffer and in the buffer pointed to by buffPtr. Every time the Disk Driver writes a sector onto the disk, it reads 12 bytes from the buffer pointed to by buffPtr, places them in the file tags buffer, and then writes them onto the disk. The contents of the buffer pointed to by buffPtr are overwritten at the end of every read request (which can be composed of a number of sectors) instead of at the end of every sector. Each read request places 12 bytes in the buffer for each sector, always beginning at the start of the buffer. This way an application can examine the file tags for a number of sequentially read sectors. If a read request is composed of a number of sectors, the Disk Driver places 12 bytes in the buffer for each sector. For example, for a read request of five sectors, the Disk Driver will place 60 bytes in the buffer. Result codes noErr No error æKY ErrMgr.p æKL AddErrInsert CloseErrMgr GetSysErrText GetToolErrText InitErrMgr æKY AddErrInsert æFp ErrMgr.p æT PROCEDURE æD PROCEDURE AddErrInsert(insert: Str255;msgString: StringPtr); C; æDT AddErrInsert(insert,msgString); æC { Add another insert to an error message string.This call is used when more than one insert is to be added to a message (because it contains more than one '^' character). } æKY CloseErrMgr æFp ErrMgr.p æT PROCEDURE æD PROCEDURE CloseErrMgr; C; æDT CloseErrMgr; æC { Ideally a CloseErrMgr should be done at the end of execution to make sure all files opened by the ErrMgr are closed. You can let normal program termination do the closing. But if you are a purist... } æKY GetSysErrText æFp ErrMgr.p æT PROCEDURE æD PROCEDURE GetSysErrText(msgNbr: INTEGER;errMsg: StringPtr); æDT GetSysErrText(msgNbr,errMsg); æC (* Get the error message text corresponding to system error number errNbr from the system error message file (whose name was specified in the InitErrMgr call). The text of the message is returned in errMsg and the function returns a pointer to errMsg. The maximum length of the message is limited to 254 characters. Note, if a system message filename was not specified to InitErrMgr, then the ErrMgr assumes the message file contained in the file "SysErrs.Err". This file is first accessed as " {ShellDirectory}SysErrs.Err" on the assumption that SysErrs.Err is kept in the same directory as the MPW Shell. If the file cannot be opened, then an open is attempted on "SysErrs.Err" in the System Folder. *) æKY GetToolErrText æFp ErrMgr.p æT PROCEDURE æD PROCEDURE GetToolErrText(msgNbr: INTEGER;errInsert: Str255;errMsg: StringPtr); æDT GetToolErrText(msgNbr,errInsert,errMsg); æC (* Get the error message text corresponding to tool error number errNbr from the tool error message file (whose name was specified in the InitErrMgr call). The text of the message is returned in errMsg and the function returns a pointer to errMsg. The maximum length of the message is limited to 254 characters. If the message is to have an insert, then ErrInsert should be a pointer to it. Otherwise it should be either be a null string or a NULL pointer. Inserts are indicated in error messages by specifying a '^' to indicate where the insert is to be placed. Note, if a tool message filename was not specified to InitErrMgr, then the ErrMgr assumes the message file contained in the data fork of the tool calling the ErrMgr. This name is contained in the Shell variable {Command} and the value of that variable is used to open the error message file. *) æKY InitErrMgr æFp ErrMgr.p æT PROCEDURE æD PROCEDURE InitErrMgr(toolErrFilename: Str255;sysErrFilename: Str255; showToolErrNbrs: BOOLEAN); æDT InitErrMgr(toolErrFilename,sysErrFilename,showToolErrNbrs); æC { ErrMgr initialization.This must be done before using any other ErrMgr routine. Set showToolErrNbrs to true if you want all tool messages to contain the error number following the message text enclosed in parentheses (e.g., "<msg txt> ([OS] Error <n>)"; system error messages always contain the error number). The toolErrFileName parameter is used to specify the name of a tool-specific error file, and should be the NULL or a null string if not used (or if the tool's data fork is to be used as the error file, see GetToolErrText for futher details). The sysErrFileName parameter is used to specify the name of a system error file, and should normally be the NULL or a null string, which causes the ErrMgr to look in the MPW Shell directory for "SysErrs.Err" (see GetSysErrText). } æKY Errors.p æKL SysError abortErr addRefFailed addResFailed afpAccessDenied afpAuthContinue afpBadUAM afpBadVersNum afpBitmapErr afpCallNotSupported afpCantMove afpCantRename afpDenyConflict afpDirNotEmpty afpDirNotFound afpDiskFull afpEofError afpFileBusy afpFlatVol afpIconTypeError afpItemNotFound afpLockErr afpMiscErr afpNoMoreLocks afpNoServer afpObjectExists afpObjectLocked afpObjectNotFound afpObjectTypeErr afpParmErr afpRangeNotLocked afpRangeOverlap afpServerGoingDown afpSessClosed afpTooManyFilesOpen afpUserNotAuth afpVolLocked aspBadVersNum aspBufTooSmall aspNoAck aspNoMoreSess aspNoServers aspParamErr aspServerBusy aspSessClosed aspSizeErr aspTooMany atpBadRsp atpLenErr badATPSkt badBtSlpErr badBuffNum badChannel badCksmErr badDBtSlp badDCksum badFormat badMDBErr badMovErr badUnitErr bdNamErr breakRecd buf2SmallErr cantStepErr cbNotFound cDevErr ckSumErr clkRdErr clkWrErr closErr cMatchErr cNoMemErr controlErr corErr cProtectErr cRangeErr cResErr cTempMemErr dataVerErr dceExtErr ddpLenErr ddpSktErr dInstErr dirFulErr dirNFErr dRemovErr dsAddressErr dsBadLaunch dsBadPatch dsBadSANEopcode dsBadSlotInt dsBusError dsChkErr dsCoreErr dsFinderErr dsFPErr dsFSErr dsGreeting dsHMenuFindErr dsIllInstErr dsIOCoreErr dsIrqErr dskFulErr dsLineAErr dsLineFErr dsLoadErr dsMBarNFnd dsMemFullErr dsMiscErr dsNoPackErr dsNoPatch dsNoPk1 dsNoPk2 dsNoPk3 dsNoPk4 dsNoPk5 dsNoPk6 dsNoPk7 dsNotThe1 dsOvflowErr dsPrivErr dsReinsert dsStknHeap dsSysErr dsTraceErr dsZeroDivErr dupFNErr envBadVers envNotPresent envVersTooBig eofErr evtNotEnb excessCollsns extFSErr extractErr exUserBreak fBsyErr firstDskErr fLckdErr fmt1Err fmt2Err fnfErr fnOpnErr fontDecError fontNotDeclared fontSubErr framingErr fsDSIntErr fsRnErr gcrOnMFMErr gfpErr hMenuFindErr hwOverrunErr hwParamErr iIOAbortErr initIWMErr ioErr lapProtErr lastDskErr mapReadErr mBarNFnd memAdrErr memAZErr memBCErr memFullErr memLockedErr memPCErr memPurErr memROZErr memROZWarn memSCErr memWZErr menuPrgErr mFulErr nbpBuffOvr nbpConfDiff nbpDuplicate nbpNISErr nbpNoConfirm nbpNotFound negZcbFreeErr nilHandleErr nmTypErr noAdrMkErr noBridgeErr noDataArea noDriveErr noDtaMkErr noErr noHardware noMacDskErr noMPPErr noNybErr noRelErr noScrapErr noSendResp notEnoughHardware notOpenErr noTypeErr nsDrvErr nsvErr offLinErr openErr opWrErr paramErr parityErr permErr portInUse portNotCf posErr prInitErr prWrErr qErr queueFull rcvrErr readErr readQErr recNotFnd reqAborted reqFailed resAttrErr resFNotFound resNotFound resProblem rfNumErr rgnTooBigErr rmvRefFailed rmvResFailed sdmInitErr sdmJTInitErr sdmPRAMInitErr sdmPriInitErr sdmSRTInitErr sectNFErr seekErr seNoDB shutDownAlert siInitSDTblErr siInitSPTblErr siInitVBLQsErr sktClosedErr slotNumErr smBadBoardId smBadRefId smBadsList smBadsPtrErr smBLFieldBad smBlkMoveErr smBusErrTO smByteLanesErr smCkStatusErr smCodeRevErr smCPUErr smCRCFail smDisDrvrNamErr smDisposePErr smEmptySlot smFHBlockRdErr smFormatErr smGetDrvrNamErr smGetPRErr smInitStatVErr smInitTblErr smLWTstBad smNewPErr smNilsBlockErr smNoBoardId smNoBoardsRsrc smNoDir smNoGoodOpens smNoJmpTbl smNoMoresRsrcs smNosInfoArray smOffsetErr smPRAMInitErr smPriInitErr smRecNotFnd smReservedErr smResrvErr smRevisionErr smSDMInitErr smSelOOBErr smsGetDrvrErr smSlotOOBErr smsPointerNil smSRTInitErr smSRTOvrFlErr smUnExBusErr spdAdjErr statusErr strUserBreak svDisabled svTempDisable swOverrunErr teScrapSizeErr tk0BadErr tmfoErr tmwdoErr tooManyReqs tooManySkts twoSideErr unimpErr unitEmptyErr unitTblFullErr updPixMemErr userBreak verErr vLckdErr volGoneErr volOffLinErr volOnLinErr vTypErr wPrErr wrgVolTypErr writErr wrPermErr wrUnderrun æKY abortErr æFp Errors.p æC abortErr = -27; {IO call aborted by KillIO} æKY addRefFailed æFp Errors.p æC addRefFailed = -195; {AddReference failed} æKY addResFailed æFp Errors.p æC addResFailed = -194; {AddResource failed} æKY afpAccessDenied æFp Errors.p æC afpAccessDenied = -5000; æKY afpAuthContinue æFp Errors.p æC afpAuthContinue = -5001; æKY afpBadUAM æFp Errors.p æC afpBadUAM = -5002; æKY afpBadVersNum æFp Errors.p æC afpBadVersNum = -5003; æKY afpBitmapErr æFp Errors.p æC afpBitmapErr = -5004; æKY afpCallNotSupported æFp Errors.p æC afpCallNotSupported = -5024; æKY afpCantMove æFp Errors.p æC afpCantMove = -5005; æKY afpCantRename æFp Errors.p æC afpCantRename = -5028; æKY afpDenyConflict æFp Errors.p æC afpDenyConflict = -5006; æKY afpDirNotEmpty æFp Errors.p æC afpDirNotEmpty = -5007; æKY afpDirNotFound æFp Errors.p æC afpDirNotFound = -5029; æKY afpDiskFull æFp Errors.p æC afpDiskFull = -5008; æKY afpEofError æFp Errors.p æC afpEofError = -5009; æKY afpFileBusy æFp Errors.p æC afpFileBusy = -5010; æKY afpFlatVol æFp Errors.p æC afpFlatVol = -5011; æKY afpIconTypeError æFp Errors.p æC afpIconTypeError = -5030; æKY afpItemNotFound æFp Errors.p æC afpItemNotFound = -5012; æKY afpLockErr æFp Errors.p æC afpLockErr = -5013; æKY afpMiscErr æFp Errors.p æC afpMiscErr = -5014; æKY afpNoMoreLocks æFp Errors.p æC afpNoMoreLocks = -5015; æKY afpNoServer æFp Errors.p æC afpNoServer = -5016; æKY afpObjectExists æFp Errors.p æC afpObjectExists = -5017; æKY afpObjectLocked æFp Errors.p æC afpObjectLocked = -5032; {Object is M/R/D/W inhibited} æKY afpObjectNotFound æFp Errors.p æC afpObjectNotFound = -5018; æKY afpObjectTypeErr æFp Errors.p æC afpObjectTypeErr = -5025; æKY afpParmErr æFp Errors.p æC afpParmErr = -5019; æKY afpRangeNotLocked æFp Errors.p æC afpRangeNotLocked = -5020; æKY afpRangeOverlap æFp Errors.p æC afpRangeOverlap = -5021; æKY afpServerGoingDown æFp Errors.p æC afpServerGoingDown = -5027; æKY afpSessClosed æFp Errors.p æC afpSessClosed = -5022; æKY afpTooManyFilesOpen æFp Errors.p æC afpTooManyFilesOpen = -5026; æKY afpUserNotAuth æFp Errors.p æC afpUserNotAuth = -5023; æKY afpVolLocked æFp Errors.p æC afpVolLocked = -5031; {Volume is Read-Only} æKY aspBadVersNum æFp Errors.p æC aspBadVersNum = -1066; {Server cannot support this ASP version} æKY aspBufTooSmall æFp Errors.p æC aspBufTooSmall = -1067; {Buffer too small} æKY aspNoAck æFp Errors.p æC aspNoAck = -1075; {No ack on attention request (server err)} æKY aspNoMoreSess æFp Errors.p æC aspNoMoreSess = -1068; {No more sessions on server} æKY aspNoServers æFp Errors.p æC aspNoServers = -1069; {No servers at that address} æKY aspParamErr æFp Errors.p æC aspParamErr = -1070; {Parameter error} æKY aspServerBusy æFp Errors.p æC aspServerBusy = -1071; {Server cannot open another session} æKY aspSessClosed æFp Errors.p æC aspSessClosed = -1072; {Session closed} æKY aspSizeErr æFp Errors.p æC aspSizeErr = -1073; {Command block too big} æKY aspTooMany æFp Errors.p æC aspTooMany = -1074; {Too many clients (server error)} æKY atpBadRsp æFp Errors.p æC atpBadRsp = -3107; æKY atpLenErr æFp Errors.p æC atpLenErr = -3106; æKY badATPSkt æFp Errors.p æC badATPSkt = -1099; æKY badBtSlpErr æFp Errors.p æC badBtSlpErr = -70; {bad addr mark bit slip nibbles} æKY badBuffNum æFp Errors.p æC badBuffNum = -1100; æKY badChannel æFp Errors.p æC badChannel = -205; {Sound Manager Error Returns} æKY badCksmErr æFp Errors.p æC badCksmErr = -69; {addr mark checksum didn't check} æKY badDBtSlp æFp Errors.p æC badDBtSlp = -73; {bad data mark bit slip nibbles} æKY badDCksum æFp Errors.p æC badDCksum = -72; {bad data mark checksum} æKY badFormat æFp Errors.p æC badFormat = -206; {Sound Manager Error Returns} æKY badMDBErr æFp Errors.p æC badMDBErr = -60; {bad master directory block} æKY badMovErr æFp Errors.p æC badMovErr = -122; {Move into offspring error} æKY badUnitErr æFp Errors.p æC badUnitErr = -21; {I/O System Errors} æKY bdNamErr æFp Errors.p æC bdNamErr = -37; {there may be no bad names in the final system!} æKY breakRecd æFp Errors.p æC breakRecd = -90; {Break received (SCC)} æKY buf2SmallErr æFp Errors.p æC buf2SmallErr = -3101; æKY cantStepErr æFp Errors.p æC cantStepErr = -75; {step handshake failed} æKY cbNotFound æFp Errors.p æC cbNotFound = -1102; æKY cDevErr æFp Errors.p æC cDevErr = -155; {invalid type of graphics device} æKY ckSumErr æFp Errors.p æC ckSumErr = -3103; æKY clkRdErr,clkWrErr,prInitErr,prWrErr,qErr æFp Errors.p æC { Result codes } clkRdErr = -85; {unable to read clock} clkWrErr = -86; {time written did not verify} memFullErr = -108; {not enough room in heap zone} memWZErr = -111; {attempt to operate on a free block} nilHandleErr = -109; {NIL master pointer} noErr = 0; {no error} prInitErr = -88; {validity status is not $A8} prWrErr = -87; {parameter RAM written did not verify} qErr = -1 {entry not in specified queue} æKY closErr æFp Errors.p æC closErr = -24; {I/O System Errors} æKY cMatchErr æFp Errors.p æC cMatchErr = -150; {Color2Index failed to find an index} æKY cNoMemErr æFp Errors.p æC cNoMemErr = -152; {failed to allocate memory for structure} æKY controlErr æFp Errors.p æC controlErr = -17; {I/O System Errors} æKY corErr æFp Errors.p æC corErr = -3; {core routine number out of range} æKY cProtectErr æFp Errors.p æC cProtectErr = -154; {colorTable entry protection violation} æKY cRangeErr æFp Errors.p æC cRangeErr = -153; {range error on colorTable request} æKY cResErr æFp Errors.p æC cResErr = -156; {invalid resolution for MakeITable} æKY cTempMemErr æFp Errors.p æC cTempMemErr = -151; {failed to allocate memory for temporary structures} æKY dataVerErr æFp Errors.p æC dataVerErr = -68; {read verify compare failed} æKY dceExtErr æFp Errors.p æC dceExtErr = -30; {dce extension error} æKY ddpLenErr æFp Errors.p æC ddpLenErr = -92; {data length too big} æKY ddpSktErr æFp Errors.p æC ddpSktErr = -91; {error in soket number} æKY dInstErr æFp Errors.p æC dInstErr = -26; {DrvrInstall couldn't find driver in resources } æKY dirFulErr æFp Errors.p æC dirFulErr = -33; {Directory full} æKY dirNFErr æFp Errors.p æC dirNFErr = -120; {Directory not found} æKY dRemovErr æFp Errors.p æC dRemovErr = -25; {tried to remove an open driver} æKY dsAddressErr æFp Errors.p æC dsAddressErr = 2; {address error} æKY dsBadLaunch æFp Errors.p æC dsBadLaunch = 26; {can't launch file} æKY dsBadPatch æFp Errors.p æC dsBadPatch = 99; {Can't load patch resource} æKY dsBadSANEopcode æFp Errors.p æC dsBadSANEopcode = 81; {bad opcode given to SANE Pack4} æKY dsBadSlotInt æFp Errors.p æC dsBadSlotInt = 51; {unserviceable slot interrupt} æKY dsBusError æFp Errors.p æC dsBusError = 1; {bus error } æKY dsChkErr æFp Errors.p æC dsChkErr = 5; {check trap error} æKY dsCoreErr æFp Errors.p æC dsCoreErr = 12; {unimplemented core routine error} æKY dsFinderErr æFp Errors.p æC dsFinderErr = 41; {can't load the Finder error} æKY dsFPErr æFp Errors.p æC dsFPErr = 16; {Floating point error} æKY dsFSErr æFp Errors.p æC dsFSErr = 27; {file system map has been trashed} æKY dsGreeting æFp Errors.p æC dsGreeting = 40; {welcome to Macintosh greeting} æKY dsHMenuFindErr æFp Errors.p æC dsHMenuFindErr = 86; {Menu Manager Errors} æKY dsIllInstErr æFp Errors.p æC dsIllInstErr = 3; {illegal instruction error} æKY dsIOCoreErr æFp Errors.p æC dsIOCoreErr = 14; {IO Core Error} æKY dsIrqErr æFp Errors.p æC dsIrqErr = 13; {uninstalled interrupt error} æKY dskFulErr æFp Errors.p æC dskFulErr = -34; {disk full} æKY dsLineAErr æFp Errors.p æC dsLineAErr = 9; {line 1010 trap error} æKY dsLineFErr æFp Errors.p æC dsLineFErr = 10; {line 1111 trap error} æKY dsLoadErr æFp Errors.p æC dsLoadErr = 15; {Segment Loader Error} æKY dsMBarNFnd æFp Errors.p æC dsMBarNFnd = 85; {Menu Manager Errors} æKY dsMemFullErr æFp Errors.p æC dsMemFullErr = 25; {out of memory!} æKY dsMiscErr æFp Errors.p æC dsMiscErr = 11; {miscellaneous hardware exception error} æKY dsNoPackErr æFp Errors.p æC dsNoPackErr = 17; {package 0 not present} æKY dsNoPatch æFp Errors.p æC dsNoPatch = 98; {Can't patch for particular Model Mac} æKY dsNoPk1 æFp Errors.p æC dsNoPk1 = 18; {package 1 not present} æKY dsNoPk2 æFp Errors.p æC dsNoPk2 = 19; {package 2 not present} æKY dsNoPk3 æFp Errors.p æC dsNoPk3 = 20; {package 3 not present} æKY dsNoPk4 æFp Errors.p æC dsNoPk4 = 21; {package 4 not present} æKY dsNoPk5 æFp Errors.p æC dsNoPk5 = 22; {package 5 not present} æKY dsNoPk6 æFp Errors.p æC dsNoPk6 = 23; {package 6 not present} æKY dsNoPk7 æFp Errors.p æC dsNoPk7 = 24; {package 7 not present} æKY dsNotThe1 æFp Errors.p æC dsNotThe1 = 31; {not the disk I wanted} æKY dsOvflowErr æFp Errors.p æC dsOvflowErr = 6; {overflow trap error} æKY dsPrivErr æFp Errors.p æC dsPrivErr = 7; {privilege violation error} æKY dsReinsert æFp Errors.p æC dsReinsert = 30; {request user to reinsert off-line volume} æKY dsStknHeap æFp Errors.p æC dsStknHeap = 28; {stack has moved into application heap} æKY dsSysErr æFp Errors.p æC dsSysErr = 32767; {general system error} æKY dsTraceErr æFp Errors.p æC dsTraceErr = 8; {trace mode error} æKY dsZeroDivErr æFp Errors.p æC dsZeroDivErr = 4; {zero divide error} æKY dupFNErr æFp Errors.p æC dupFNErr = -48; {duplicate filename (rename)} æKY envBadVers æFp Errors.p æC envBadVers = -5501; {Version non-positive} æKY envNotPresent æFp Errors.p æC envNotPresent = -5500; {returned by glue.} æKY envVersTooBig æFp Errors.p æC envVersTooBig = -5502; {Version bigger than call can handle} æKY eofErr æFp Errors.p æC eofErr = -39; {End of file} æKY evtNotEnb æFp Errors.p æC evtNotEnb = 1; {event not enabled at PostEvent} æKY excessCollsns æFp Errors.p æC excessCollsns = -95; {excessive collisions on write} æKY extFSErr æFp Errors.p æC extFSErr = -58; {volume in question belongs to an external fs} æKY extractErr æFp Errors.p æC extractErr = -3104; æKY exUserBreak æFp Errors.p æC exUserBreak = -492; {user debugger break; execute debugger commands on stack} æKY fBsyErr æFp Errors.p æC fBsyErr = -47; {File is busy (delete)} æKY firstDskErr æFp Errors.p æC firstDskErr = -84; {I/O System Errors} æKY fLckdErr æFp Errors.p æC fLckdErr = -45; {file is locked} æKY fmt1Err æFp Errors.p æC fmt1Err = -82; {can't find sector 0 after track format} æKY fmt2Err æFp Errors.p æC fmt2Err = -83; {can't get enough sync} æKY fnfErr æFp Errors.p æC fnfErr = -43; {File not found} æKY fnOpnErr æFp Errors.p æC fnOpnErr = -38; {File not open} æKY fontDecError æFp Errors.p æC fontDecError = -64; {error during font declaration} æKY fontNotDeclared æFp Errors.p æC fontNotDeclared = -65; {font not declared} æKY fontSubErr æFp Errors.p æC fontSubErr = -66; {font substitution occured} æKY framingErr æFp Errors.p æC framingErr = 64; {serial driver error masks} æKY fsDSIntErr æFp Errors.p æC fsDSIntErr = -127; {Internal file system error} æKY fsRnErr æFp Errors.p æC fsRnErr = -59; {file system internal error:during rename the old entry was deleted but could not be restored.} æKY gcrOnMFMErr æFp Errors.p æC gcrOnMFMErr = -400; {gcr format on high density media error} æKY gfpErr æFp Errors.p æC gfpErr = -52; {get file position error} æKY hMenuFindErr æFp Errors.p æC hMenuFindErr = -127; {could not find HMenu's parent in MenuKey} æKY hwOverrunErr æFp Errors.p æC hwOverrunErr = 32; {serial driver error masks} æKY hwParamErr æFp Errors.p æC hwParamErr = -502; {bad selector for _HWPriv} æKY iIOAbortErr æFp Errors.p æC iIOAbortErr = -27; {IO abort error (Printing Manager)} æKY initIWMErr æFp Errors.p æC initIWMErr = -77; {unable to initialize IWM} æKY ioErr æFp Errors.p æC ioErr = -36; {I/O error (bummers)} æKY lapProtErr æFp Errors.p æC lapProtErr = -94; {error in attaching/detaching protocol} æKY lastDskErr æFp Errors.p æC lastDskErr = -64; {I/O System Errors} æKY mapReadErr æFp Errors.p æC mapReadErr = -199; {map inconsistent with operation} æKY mBarNFnd æFp Errors.p æC mBarNFnd = -126; {system error code for MBDF not found} æKY memAdrErr æFp Errors.p æC memAdrErr = -110; {address was odd; or out of range} æKY memAZErr æFp Errors.p æC memAZErr = -113; {Address in zone check failed} æKY memBCErr æFp Errors.p æC memBCErr = -115; {Block Check failed} æKY memPCErr æFp Errors.p æC memPCErr = -114; {Pointer Check failed} æKY memROZErr,memFullErr,memLockedErr,memPurErr,memWZErr,nilHandleErr,noErr æFp Errors.p æC { Result codes for Memory Manager } memROZErr = -99; {operation on a read-only zone} memFullErr = -108; {not enough room in heap zone} memLockedErr = -117; {block is locked} memPurErr = -112; {attempt to purge a locked block} memWZErr = -111; {attempt to operate on a free block} nilHandleErr = -109; {NIL master pointer} noErr = 0; {no error} æKY memROZWarn æFp Errors.p æC memROZWarn = -99; {soft error in ROZ} æKY memSCErr æFp Errors.p æC memSCErr = -116; {Size Check failed} æKY menuPrgErr æFp Errors.p æC menuPrgErr = 84; {happens when a menu is purged} æKY mFulErr æFp Errors.p æC mFulErr = -41; {memory full (open) or file won't fit (load)} æKY nbpBuffOvr æFp Errors.p æC nbpBuffOvr = -1024; {Buffer overflow in LookupName} æKY nbpConfDiff æFp Errors.p æC nbpConfDiff = -1026; {Name confirmed at different socket} æKY nbpDuplicate æFp Errors.p æC nbpDuplicate = -1027; {Duplicate name exists already} æKY nbpNISErr æFp Errors.p æC nbpNISErr = -1029; {Error trying to open the NIS} æKY nbpNoConfirm æFp Errors.p æC nbpNoConfirm = -1025; æKY nbpNotFound æFp Errors.p æC nbpNotFound = -1028; {Name not found on remove} æKY negZcbFreeErr æFp Errors.p æC negZcbFreeErr = 33; {ZcbFree has gone negative} æKY nmTypErr æFp Errors.p æC nmTypErr = -299; æKY noAdrMkErr æFp Errors.p æC noAdrMkErr = -67; {couldn't find valid addr mark} æKY noBridgeErr æFp Errors.p æC noBridgeErr = -93; {no network bridge for non-local send} æKY noDataArea æFp Errors.p æC noDataArea = -1104; æKY noDriveErr æFp Errors.p æC noDriveErr = -64; {drive not installed} æKY noDtaMkErr æFp Errors.p æC noDtaMkErr = -71; {couldn't find a data mark header} æKY noHardware æFp Errors.p æC noHardware = -200; {Sound Manager Error Returns} æKY noMacDskErr æFp Errors.p æC noMacDskErr = -57; {not a mac diskette (sig bytes are wrong)} æKY noMPPErr æFp Errors.p æC noMPPErr = -3102; æKY noNybErr æFp Errors.p æC noNybErr = -66; {couldn't find 5 nybbles in 200 tries} æKY noRelErr æFp Errors.p æC noRelErr = -1101; æKY noScrapErr,noTypeErr æFp Errors.p æC { Scrap Manager result codes } noScrapErr = -100; {desk scrap isn't initialized} noTypeErr = -102; {no data of the requested type} æKY noSendResp æFp Errors.p æC noSendResp = -1103; æKY notEnoughHardware æFp Errors.p æC notEnoughHardware = -201; {Sound Manager Error Returns} æKY notOpenErr æFp Errors.p æC notOpenErr = -28; {Couldn't rd/wr/ctl/sts cause driver not opened} æKY nsDrvErr æFp Errors.p æC nsDrvErr = -56; {no such drive (tried to mount a bad drive num)} æKY nsvErr æFp Errors.p æC nsvErr = -35; {no such volume} æKY offLinErr æFp Errors.p æC offLinErr = -65; {r/w requested for an off-line drive} æKY openErr æFp Errors.p æC openErr = -23; {I/O System Errors} æKY opWrErr æFp Errors.p æC opWrErr = -49; {file already open with with write permission} æKY paramErr æFp Errors.p æC paramErr = -50; {error in user parameter list} æKY parityErr æFp Errors.p æC parityErr = 16; {serial driver error masks} æKY permErr æFp Errors.p æC permErr = -54; {permissions error (on file open)} æKY portInUse æFp Errors.p æC portInUse = -97; {driver Open error code (port is in use)} æKY portNotCf æFp Errors.p æC portNotCf = -98; {driver Open error code (parameter RAM not configured for this connection)} æKY posErr æFp Errors.p æC posErr = -40; {tried to position to before start of file (r/w)} æKY queueFull æFp Errors.p æC queueFull = -203; {Sound Manager Error Returns} æKY rcvrErr æFp Errors.p æC rcvrErr = -89; {SCC receiver error (framing; parity; OR)} æKY readErr æFp Errors.p æC readErr = -19; {I/O System Errors} æKY readQErr æFp Errors.p æC readQErr = -3105; æKY recNotFnd æFp Errors.p æC recNotFnd = -3108; æKY reqAborted æFp Errors.p æC reqAborted = -1105; æKY reqFailed æFp Errors.p æC reqFailed = -1096; æKY resAttrErr æFp Errors.p æC resAttrErr = -198; {attribute inconsistent with operation} æKY resFNotFound æFp Errors.p æC resFNotFound = -193; {Resource file not found} æKY resNotFound æFp Errors.p æC resNotFound = -192; {Resource not found} æKY resProblem æFp Errors.p æC resProblem = -204; {Sound Manager Error Returns} æKY rfNumErr æFp Errors.p æC rfNumErr = -51; {refnum error} æKY rgnTooBigErr æFp Errors.p æC rgnTooBigErr = -500; æKY rmvRefFailed æFp Errors.p æC rmvRefFailed = -197; {RmveReference failed} æKY rmvResFailed æFp Errors.p æC rmvResFailed = -196; {RmveResource failed} æKY sdmInitErr æFp Errors.p æC sdmInitErr = 11; {SDM could not be initialized.} æKY sdmJTInitErr æFp Errors.p æC sdmJTInitErr = 10; {SDM Jump Table could not be initialized.} æKY sdmPRAMInitErr æFp Errors.p æC sdmPRAMInitErr = 13; {Slot PRAM could not be initialized.} æKY sdmPriInitErr æFp Errors.p æC sdmPriInitErr = 14; {Cards could not be initialized.} æKY sdmSRTInitErr æFp Errors.p æC sdmSRTInitErr = 12; {Slot Resource Table could not be initialized.} æKY sectNFErr æFp Errors.p æC sectNFErr = -81; {sector number never found on a track} æKY seekErr æFp Errors.p æC seekErr = -80; {track number wrong on address mark} æKY seNoDB æFp Errors.p æC seNoDB = -8; {no debugger installed to handle debugger command} æKY shutDownAlert æFp Errors.p æC shutDownAlert = 42; {handled like a shutdown error} æKY siInitSDTblErr æFp Errors.p æC siInitSDTblErr = 1; {slot int dispatch table could not be initialized.} æKY siInitSPTblErr æFp Errors.p æC siInitSPTblErr = 3; {slot priority table could not be initialized.} æKY siInitVBLQsErr æFp Errors.p æC siInitVBLQsErr = 2; {VBLqueues for all slots could not be initialized.} æKY sktClosedErr æFp Errors.p æC sktClosedErr = -3109; æKY slotNumErr æFp Errors.p æC slotNumErr = -360; {invalid slot # error} æKY smBadBoardId æFp Errors.p æC smBadBoardId = -319; {BoardId was wrong; re-init the PRAM record.} æKY smBadRefId æFp Errors.p æC smBadRefId = -330; {Reference Id not found in List} æKY smBadsList æFp Errors.p æC smBadsList = -331; {Bad sList: Id1 < Id2 < Id3 ...format is not followed.} æKY smBadsPtrErr æFp Errors.p æC smBadsPtrErr = -346; {Bad pointer was passed to sCalcsPointer} æKY smBLFieldBad æFp Errors.p æC smBLFieldBad = -309; {ByteLanes field was bad.} æKY smBlkMoveErr æFp Errors.p æC smBlkMoveErr = -340; {_BlockMove error} æKY smBusErrTO æFp Errors.p æC smBusErrTO = -320; {BusError time out.} æKY smByteLanesErr æFp Errors.p æC smByteLanesErr = -347; {NumByteLanes was determined to be zero.} æKY smCkStatusErr æFp Errors.p æC smCkStatusErr = -341; {Status of slot = fail.} æKY smCodeRevErr æFp Errors.p æC smCodeRevErr = -333; {Code revision is wrong} æKY smCPUErr æFp Errors.p æC smCPUErr = -334; {Code revision is wrong} æKY smCRCFail æFp Errors.p æC smCRCFail = -301; {CRC check failed for declaration data} æKY smDisDrvrNamErr æFp Errors.p æC smDisDrvrNamErr = -343; {Error occured during _sDisDrvrName.} æKY smDisposePErr æFp Errors.p æC smDisposePErr = -312; {_DisposePointer error} æKY smEmptySlot æFp Errors.p æC smEmptySlot = -300; {No card in slot} æKY smFHBlockRdErr æFp Errors.p æC smFHBlockRdErr = -310; {Error occured during _sGetFHeader.} æKY smFormatErr æFp Errors.p æC smFormatErr = -302; {FHeader Format is not Apple's} æKY smGetDrvrNamErr æFp Errors.p æC smGetDrvrNamErr = -342; {Error occured during _sGetDrvrName.} æKY smGetPRErr æFp Errors.p æC smGetPRErr = -314; {Error occured during _sGetPRAMRec (See SIMStatus).} æKY smInitStatVErr æFp Errors.p æC smInitStatVErr = -316; {The InitStatusV field was negative after primary or secondary init.} æKY smInitTblErr æFp Errors.p æC smInitTblErr = -317; {An error occured while trying to initialize the Slot Resource Table.} æKY smLWTstBad æFp Errors.p æC smLWTstBad = -305; {Long Word test field <> $5A932BC7.} æKY smNewPErr æFp Errors.p æC smNewPErr = -339; {_NewPtr error} æKY smNilsBlockErr æFp Errors.p æC smNilsBlockErr = -336; {Nil sBlock error (Dont allocate and try to use a nil sBlock)} æKY smNoBoardId æFp Errors.p æC smNoBoardId = -315; {No Board Id.} æKY smNoBoardsRsrc æFp Errors.p æC smNoBoardsRsrc = -313; {No Board sResource.} æKY smNoDir æFp Errors.p æC smNoDir = -304; {Directory offset is Nil } æKY smNoGoodOpens æFp Errors.p æC smNoGoodOpens = -349; {No opens were successfull in the loop.} æKY smNoJmpTbl æFp Errors.p æC smNoJmpTbl = -318; {SDM jump table could not be created.} æKY smNoMoresRsrcs æFp Errors.p æC smNoMoresRsrcs = -344; {No more sResources} æKY smNosInfoArray æFp Errors.p æC smNosInfoArray = -306; {No sInfoArray. Memory Mgr error.} æKY smOffsetErr æFp Errors.p æC smOffsetErr = -348; {Offset was too big (temporary error} æKY smPRAMInitErr æFp Errors.p æC smPRAMInitErr = -292; {Error; Slot Resource Table could not be initialized.} æKY smPriInitErr æFp Errors.p æC smPriInitErr = -293; {Error; Cards could not be initialized.} æKY smRecNotFnd æFp Errors.p æC smRecNotFnd = -351; {Record not found in the SRT.} æKY smReservedErr æFp Errors.p æC smReservedErr = -332; {Reserved field not zero} æKY smResrvErr æFp Errors.p æC smResrvErr = -307; {Fatal reserved error. Resreved field <> 0.} æKY smRevisionErr æFp Errors.p æC smRevisionErr = -303; {Wrong revison level} æKY smSDMInitErr æFp Errors.p æC smSDMInitErr = -290; {Error; SDM could not be initialized.} æKY smSelOOBErr æFp Errors.p æC smSelOOBErr = -338; {Selector out of bounds error} æKY smsGetDrvrErr æFp Errors.p æC smsGetDrvrErr = -345; {Error occurred during _sGetDriver.} æKY smSlotOOBErr æFp Errors.p æC smSlotOOBErr = -337; {Slot out of bounds error} æKY smsPointerNil æFp Errors.p æC smsPointerNil = -335; {LPointer is nil From sOffsetData. If this error occurs; check sInfo rec for more information.} æKY smSRTInitErr æFp Errors.p æC smSRTInitErr = -291; {Error; Slot Resource Table could not be initialized.} æKY smSRTOvrFlErr æFp Errors.p æC smSRTOvrFlErr = -350; {SRT over flow.} æKY smUnExBusErr æFp Errors.p æC smUnExBusErr = -308; {Unexpected BusError} æKY spdAdjErr æFp Errors.p æC spdAdjErr = -79; {unable to correctly adjust disk speed} æKY statusErr æFp Errors.p æC statusErr = -18; {I/O System Errors} æKY strUserBreak æFp Errors.p æC strUserBreak = -491; {user debugger break; display string on stack} æKY svDisabled æFp Errors.p æC svDisabled = -32640; {Reserve range -32640 to -32768 for Apple temp disables.} æKY svTempDisable æFp Errors.p æC svTempDisable = -32768; {Temporarily disable card but run primary init.} æKY swOverrunErr æFp Errors.p æC swOverrunErr = 1; {serial driver error masks} æKY SysError æFp Errors.p æT PROCEDURE æTN $A9C9 æD PROCEDURE SysError(errorCode: INTEGER); æDT SysError(errorCode); æMM æRI SysError procedure II-362, V-572 æC _____________________________________________________________________________________ Trap macro _SysError On entry D0: errorCode (word) On exit All registers changed _____________________________________________________________________________________ SysError generates a system error with the ID specified by the errorCode parameter. It takes the following precise steps: 1. It saves all registers and the stack pointer. 2. It stores the system error ID in a global variable (named DSErrCode). 3. It checks to see whether there's a system error alert table in memory (by testing whether the global variable DSAlertTab is 0); if there isn't, it draws the "sad Macintosh" icon. 4. It allocates memory for QuickDraw globals on the stack, initializes QuickDraw, and initializes a grafPort in which the alert box will be drawn. 5. It checks the system error ID. If the system error ID is negative, the alert box isn't redrawn (this is used for system startup alerts, which can display a sequence of consecutive messages in the same box). If the system error ID doesn't correspond to an entry in the system error alert table, the default alert definition at the start of the table will be used, displaying the message "Sorry, a system error occurred". 6. It draws an alert box (in the rectangle specified by the global variable DSAlertRect). 7. If the text definition IDs in the alert definition for this alert aren't 0, it draws both strings. 8. If the icon definition ID in the alert definition isn't 0, it draws the icon. 9. If the procedure definition ID in the alert definition isn't 0, it invokes the procedure with the specified ID. 10. If the button definition ID in the alert definition is 0, it returns control to the procedure that called it (this is used during the disk-switch alert to return control to the File Manager after the "Please insert the disk:" message has been displayed). 11. If there's a resume procedure, it increments the button definition ID by 1. 12. It draws the buttons. 13. It hit-tests the buttons and calls the corresponding procedure code when a button is pressed. If there's no procedure code, it returns to the procedure that called it. User Alerts _____________ ID Explanation 1 Bus error: Invalid memory reference; happens only on a Macintosh XL 2 Address error: Word or long-word reference made to an odd address 3 Illegal instruction: The MC68000 received an instruction it didn't recognize. 4 Zero divide: Signed Divide (DIVS) or Unsigned Divide (DIVU) instruction with a divisor of 0 was executed. 5 Check exception: Check Register Against Bounds (CHK) instruction was executed and failed. Pascal "value out of range" errors are usually reported in this way. 6 TrapV exception: Trap On Overflow (TRAPV) instruction was executed and failed. 7 Privilege violation: Macintosh always runs in supervisor mode; perhaps an erroneous Return From Execution (RTE) instruction was executed. 8 Trace exception: The trace bit in the status register is set. 9 Line 1010 exception: The 1010 trap dispatcher has failed. 10 Line 1111 exception: Unimplemented instruction 11 Miscellaneous exception: All other MC68000 exceptions 12 Unimplemented core routine: An unimplemented trap number was encountered. 13 Spurious interrupt: The interrupt vector table entry for a particular level of interrupt is NIL; usually occurs with level 4, 5, 6, or 7 interrupts. 14 I/O system error: The File Manager is attempting to dequeue an entry from an I/O request queue that has a bad queue type field; perhaps the queue entry is unlocked. Or, the dCtlQHead field was NIL during a Fetch or Stash call. Or, a needed device control entry has been purged. 15 Segment Loader error: A GetResource call to read a segment into memory failed. 16 Floating point error: The halt bit in the floating-point environment word was set. 17-24 Can't load package: A GetResource call to read a package into memory failed. 25 Can't allocate requested memory block in the heap 26 Segment Loader error: A GetResource call to read 'CODE' resource 0 into memory failed; usually indicates a nonexecutable file. 27 File map destroyed: A logical block number was found that's greater than the number of the last logical block on the volume or less than the logical block number of the first allocation block on the volume. 28 Stack overflow error: The stack has expanded into the heap. 30 "Please insert the disk:" File Manager alert 41 The file named "Finder" can't be found on the disk. 100 Can't mount system startup volume. The system couldn't read the system resource file into memory. 32767 "Sorry, a system error occurred": Default alert message æKY teScrapSizeErr æFp Errors.p æC teScrapSizeErr = -501; {scrap item too big for text edit record} æKY tk0BadErr æFp Errors.p æC tk0BadErr = -76; {track 0 detect doesn't change} æKY tmfoErr æFp Errors.p æC tmfoErr = -42; {too many files open} æKY tmwdoErr æFp Errors.p æC tmwdoErr = -121; {No free WDCB available} æKY tooManyReqs æFp Errors.p æC tooManyReqs = -1097; æKY tooManySkts æFp Errors.p æC tooManySkts = -1098; æKY twoSideErr æFp Errors.p æC twoSideErr = -78; {tried to read 2nd side on a 1-sided drive} æKY unimpErr æFp Errors.p æC unimpErr = -4; {unimplemented core routine} æKY unitEmptyErr æFp Errors.p æC unitEmptyErr = -22; {I/O System Errors} æKY unitTblFullErr æFp Errors.p æC unitTblFullErr = -29; {unit table has no more entries} æKY updPixMemErr æFp Errors.p æC updPixMemErr = -125; {insufficient memory to update a pixmap} æKY userBreak æFp Errors.p æC userBreak = -490; {user debugger break} æKY verErr æFp Errors.p æC verErr = -84; {track failed to verify} æKY vLckdErr æFp Errors.p æC vLckdErr = -46; {volume is locked} æKY volGoneErr æFp Errors.p æC volGoneErr = -124; {Server volume has been disconnected.} æKY volOffLinErr æFp Errors.p æC volOffLinErr = -53; {volume not on line error (was Ejected)} æKY volOnLinErr æFp Errors.p æC volOnLinErr = -55; {drive volume already on-line at MountVol} æKY vTypErr æFp Errors.p æC vTypErr = -2; {invalid queue element} æKY wPrErr æFp Errors.p æC wPrErr = -44; {diskette is write protected.} æKY wrgVolTypErr æFp Errors.p æC wrgVolTypErr = -123; {Wrong volume type error [operation not supported for MFS]} æKY writErr æFp Errors.p æC writErr = -20; {I/O System Errors} æKY wrPermErr æFp Errors.p æC wrPermErr = -61; {write permissions error} æKY wrUnderrun æFp Errors.p æC wrUnderrun = -74; {write underrun occurred} æKY Events.p æKL Button EventAvail GetCaretTime GetDblTime GetKeys GetMouse GetNextEvent KeyTrans StillDown TickCount WaitMouseUp WaitNextEvent activateEvt activeFlag activMask adbAddrMask alphaLock app1Evt app1Mask app2Evt app2Mask app3Evt app3Mask app4Evt app4Mask autoKey autoKeyMask btnState charCodeMask cmdKey controlKey diskEvt diskMask driverEvt driverMask EventRecord everyEvent keyCodeMask keyDown keyDownMask KeyMap KeyTrans KeyTrans keyUp keyUpMask mDownMask mouseDown mouseUp mUpMask networkEvt networkMask nullEvent optionKey shiftKey StillDown StillDown TickCount TickCount updateEvt updateMask æKY activeFlag,btnState,cmdKey,shiftKey,alphaLock,optionKey,controlKey æFp Events.p æC »Modifier Flags As mentioned above, the modifiers field of an event record contains further information about activate events and the state of the modifier keys and mouse button at the time the event was posted (see Figure 7). You might look at this field to find out, for instance, whether the Command key was down when a mouse-down event was posted (which in many applications affects the way objects are selected) or when a key-down event was posted (which could mean the user is choosing a menu item by typing its keyboard equivalent). •••Refer to Figure 7.••• Figure 7–Modifier Flags The following predefined constants are useful as masks for reading the flags in the modifiers field: CONST activeFlag = 1; {set if window being activated} btnState = 128; {set if mouse button up} cmdKey = 256; {set if Command key down} shiftKey = 512; {set if Shift key down} alphaLock = 1024; {set if Caps Lock key down} optionKey = 2048; {set if Option key down} controlKey = 4096; {set if Control key down} The activeFlag bit gives further information about activate events; it’s set if the window pointed to by the event message is being activated, or 0 if the window is being deactivated. The remaining bits indicate the state of the mouse button and modifier keys. Notice that the btnState bit is set if the mouse button is up, whereas the bits for the four modifier keys are set if their corresponding keys are down. æKY adbAddrMask æFp Events.p æC adbAddrMask = $00FF0000; æKY Button æFp Events.p æT FUNCTION æTN $A974 æD FUNCTION Button: BOOLEAN; æDT myVariable := Button; æMM æRI Button function I-259 æC The Button function returns TRUE if the mouse button is currently down, and FALSE if it isn’t. æKY charCodeMask,keyCodeMask æFp Events.p æC The following predefined constants are available to help you access the character code and key code: CONST charCodeMask = $000000FF; {character code} keyCodeMask = $0000FF00; {key code} æKY EventAvail æFp Events.p æT FUNCTION æTN $A971 æD FUNCTION EventAvail(eventMask: INTEGER;VAR theEvent: EventRecord): BOOLEAN; æDT myVariable := EventAvail(eventMask,theEvent); æMM æRT 194 æRI EventAvail function I-259 æC EventAvail works exactly the same as GetNextEvent except that if the event is in the event queue, it’s left there. Note: An event returned by EventAvail will not be accessible later if in the meantime the queue becomes full and the event is discarded from it; since the events discarded are always the oldest ones in the queue, however, this will happen only in an unusually busy environment. æKY EventRecord æFp Events.p æT RECORD æC EventRecord = RECORD what: INTEGER; message: LONGINT; when: LONGINT; where: Point; modifiers: INTEGER; END; _______________________________________________________________________________ »EVENT RECORDS _______________________________________________________________________________ Every event is represented internally by an event record containing all pertinent information about that event. The event record includes the following information: • the type of event • the time the event was posted (in ticks since system startup) • the location of the mouse at the time the event was posted (in global coordinates) • the state of the mouse button and modifier keys at the time the event was posted • any additional information required for a particular type of event, such as which key the user pressed or which window is being activated Every event has an event record containing this information—even null events. Event records are defined as follows: TYPE EventRecord = RECORD what: INTEGER; {event code} message: LONGINT; {event message} when: LONGINT; {ticks since startup} where: Point; {mouse location} modifiers: INTEGER {modifier flags} END; The when field contains the number of ticks since the system last started up, and the where field gives the location of the mouse, in global coordinates, at the time the event was posted. The other three fields are described below. _______________________________________________________________________________ »Event Code The what field of an event record contains an event code identifying the type of the event. The event codes are available as predefined constants: CONST nullEvent = 0; {null} mouseDown = 1; {mouse-down} mouseUp = 2; {mouse-up} keyDown = 3; {key-down} keyUp = 4; {key-up} autoKey = 5; {auto-key} updateEvt = 6; {update} diskEvt = 7; {disk-inserted} activateEvt = 8; {activate} networkEvt = 10; {network} driverEvt = 11; {device driver} app1Evt = 12; {application-defined} app2Evt = 13; {application-defined} app3Evt = 14; {application-defined} app4Evt = 15; {application-defined} _______________________________________________________________________________ »Event Message The message field of an event record contains the event message, which conveys additional important information about the event. The nature of this information depends on the event type, as summarized in the following table and described below. Event type Event message Keyboard Character code, key code, and ADB address field Activate, update Pointer to window Disk-inserted Drive number in low-order word, File Manager result code in high-order word Mouse-down, Undefined mouse-up, null Network Handle to parameter block Device driver See chapter describing driver Application-defined Whatever you wish For keyboard events, the low-order byte of the low-order word of the event message contains the ASCII character code generated by the key or combination of keys that was pressed or released; usually this is all you’ll need. However, as described in the Apple Desktop Bus chapter, the Macintosh II and SE can be connected to multiple keyboards. To identify the origin of keyboard events, the keyboard event message contains a new ADB address field. It now has the structure shown in Figure 2. Warning: The high byte of the event message for keyboard events is reserved for future use, and is not presently guaranteed to be zero. The event message for non-keyboard events remains the same as described above. •••Refer to Figure 2.••• Figure 2–Event Message for Keyboard Events The key code in the event message for a keyboard event represents the character key that was pressed or released; this value is always the same for any given character key, regardless of the modifier keys pressed along with it. Key codes are useful in special cases—in a music generator, for example—where you want to treat the keyboard as a set of keys unrelated to characters. Figure 3 gives the key codes for all the keys on the keyboard and keypad. (Key codes are shown for modifier keys here because they’re meaningful in other contexts, as explained later.) Both the U.S. and international keyboards are shown; in some cases the codes are quite different (for example, space and Enter are reversed). Three keyboards are now available as standard equipment with Macintosh computers sold in the U.S. They are • The Macintosh Plus Keyboard, which includes cursor control keys and an integral keypad. Its layout and key coding is shown in Figure 4. • The Macintosh II Keyboard, also shipped with the Macintosh SE, which adds Esc (Escape) and Control keys and is connected to the Apple Desktop Bus. Its layout and key coding is shown in Figure 5. • The Apple Extended Keyboard, which the user may connect to the Apple Desktop Bus of any Macintosh II or Macintosh SE computer. Its layout and key coding is shown in Figure 6. These figures show the virtual key codes for each key; they are the key codes that actually appear in keyboard events. In the case of the Macintosh II and Apple Extended Keyboards, however, the hardware produces raw key codes, which may be different. Raw key codes are translated to virtual key codes by the 'KMAP' resource in the System Folder. By modifying the 'KMAP' resource you can change the key codes for any keys. Similarly, you can change the ASCII codes corresponding to specific key codes by modifying the 'KCHR' resource in the System Folder. The 'KMAP' and 'KCHR' resources are described in the Resource Manager chapter. With both the Macintosh II and the Apple Extended keyboards, the standard 'KMAP' resource supplied in the system folder reassigns the following raw key codes to different virtual key codes: Key Raw key code Virtual key code Control 36 3B Left cursor 3B 7B Right cursor 3C 7C Down cursor 3D 7D Up cursor 3E 7E The standard 'KMAP' resource leaves all other raw key codes and virtual key codes the same. With the Apple Extended Keyboard, the virtual key codes for three more keys may be easily reassigned, as described above under “Reassigning Right Key Codes”. The following predefined constants are available to help you access the character code and key code: CONST charCodeMask = $000000FF; {character code} keyCodeMask = $0000FF00; {key code} •••Refer to Figure 3.••• Figure 3–Key Codes •••Refer to Figure 4.••• Figure 4–Macintosh Plus Keyboard •••Refer to Figure 5.••• Figure 5–Macintosh II Keyboard •••Refer to Figure 6.••• Figure 6–Apple Extended Keyboard Note: You can use the Toolbox Utility function BitAnd with these constants; for instance, to access the character code, use charCode := BitAnd(my Event.message,charCodeMask) _______________________________________________________________________________ THE TOOLBOX EVENT MANAGER _______________________________________________________________________________ For activate and update events, the event message is a pointer to the window affected. (If the event is an activate event, additional important information about the event can be found in the modifiers field of the event record, as described below.) For disk-inserted events, the low-order word of the event message contains the drive number of the disk drive into which the disk was inserted: 1 for the Macintosh’s built-in drive, and 2 for the external drive, if any. Numbers greater than 2 denote additional disk drives connected to the Macintosh. By the time your application receives a disk-inserted event, the system will already have attempted to mount the volume on the disk by calling the File Manager function MountVol; the high-order word of the event message will contain the result code returned by MountVol. For mouse-down, mouse-up, and null events, the event message is undefined and should be ignored. The event message for a network event contains a handle to a parameter block, as described in the AppleTalk Manager chapter. For device driver events, the contents of the event message depend on the situation under which the event was generated; the chapters describing those situations will give the details. Finally, you can use the event message however you wish for application-defined event types. _______________________________________________________________________________ »Modifier Flags As mentioned above, the modifiers field of an event record contains further information about activate events and the state of the modifier keys and mouse button at the time the event was posted (see Figure 7). You might look at this field to find out, for instance, whether the Command key was down when a mouse-down event was posted (which in many applications affects the way objects are selected) or when a key-down event was posted (which could mean the user is choosing a menu item by typing its keyboard equivalent). •••Refer to Figure 7.••• Figure 7–Modifier Flags The following predefined constants are useful as masks for reading the flags in the modifiers field: CONST activeFlag = 1; {set if window being activated} btnState = 128; {set if mouse button up} cmdKey = 256; {set if Command key down} shiftKey = 512; {set if Shift key down} alphaLock = 1024; {set if Caps Lock key down} optionKey = 2048; {set if Option key down} controlKey = 4096; {set if Control key down} The activeFlag bit gives further information about activate events; it’s set if the window pointed to by the event message is being activated, or 0 if the window is being deactivated. The remaining bits indicate the state of the mouse button and modifier keys. Notice that the btnState bit is set if the mouse button is up, whereas the bits for the four modifier keys are set if their corresponding keys are down. æKY everyEvent æFp Events.p æC everyEvent = -1; æKY GetCaretTime æFp Events.p æT FUNCTION æD FUNCTION GetCaretTime: LONGINT; æDT myVariable := GetCaretTime; æRI GetCaretTime function I-260 æC [Not in ROM] GetCaretTime returns the time (in ticks) between blinks of the “caret” (usually a vertical bar) marking the insertion point in editable text. If you aren’t using TextEdit, you’ll need to cause the caret to blink yourself; on every pass through your program’s main event loop, you should check this value against the elapsed time since the last blink of the caret. The user can adjust this value by means of the Control Panel desk accessory. Assembly-language note: This value is available to assembly-language programmers in the global variable CaretTime. æKY GetDblTime æFp Events.p æT FUNCTION æD FUNCTION GetDblTime: LONGINT; æDT myVariable := GetDblTime; æRI GetDblTime function I-260 æC [Not in ROM] GetDblTime returns the suggested maximum difference (in ticks) that should exist between the times of a mouse-up event and a mouse-down event for those two mouse clicks to be considered a double-click. The user can adjust this value by means of the Control Panel desk accessory. Assembly-language note: This value is available to assembly-language programmers in the global variable DoubleTime. æKY GetKeys æFp Events.p æT PROCEDURE æTN $A976 æD PROCEDURE GetKeys(VAR theKeys: KeyMap); æDT GetKeys(theKeys); æMM æRI GetKeys procedure I-259 æC GetKeys reads the current state of the keyboard (and keypad, if any) and returns it in the form of a keyMap: TYPE KeyMap = PACKED ARRAY[0..127] OF BOOLEAN; Each key on the keyboard or keypad corresponds to an element in the keyMap. The index into the keyMap for a particular key is the same as the key code for that key. (The key codes are shown in Figure 3 above.) The keyMap element is TRUE if the corresponding key is down and FALSE if it isn’t. The maximum number of keys that can be down simultaneously is two character keys plus any combination of the four modifier keys. æKY GetMouse æFp Events.p æT PROCEDURE æTN $A972 æD PROCEDURE GetMouse(VAR mouseLoc: Point); æDT GetMouse(mouseLoc); æMM æRI GetMouse procedure I-259 æC GetMouse returns the current mouse location in the mouseLoc parameter. The location is given in the local coordinate system of the current grafPort (which might be, for example, the currently active window). Notice that this differs from the mouse location stored in the where field of an event record; that location is always in global coordinates. æKY GetNextEvent æFp Events.p æT FUNCTION æTN $A970 æD FUNCTION GetNextEvent(eventMask: INTEGER;VAR theEvent: EventRecord): BOOLEAN; æDT myVariable := GetNextEvent(eventMask,theEvent); æMM æRT 3, 5, 85, 194, 205 æRI GetNextEvent function I-257, N3-1, N5-1, N85, P-30, 32, 34, 39, 40, 97, 108, 173 æC GetNextEvent returns the next available event of a specified type or types and, if the event is in the event queue, removes it from the queue. The event is returned in the parameter theEvent. The eventMask parameter specifies which event types are of interest. GetNextEvent returns the next available event of any type designated by the mask, subject to the priority rules discussed above under “Priority of Events”. If no event of any of the designated types is available, GetNextEvent returns a null event. Note: Events in the queue that aren’t designated in the mask are kept in the queue; if you want to remove them, you can do so by calling the Operating System Event Manager procedure FlushEvents. Before reporting an event to your application, GetNextEvent first calls the Desk Manager function SystemEvent to see whether the system wants to intercept and respond to the event. If so, or if the event being reported is a null event, GetNextEvent returns a function result of FALSE; a function result of TRUE means that your application should handle the event itself. The Desk Manager intercepts the following events: • activate and update events directed to a desk accessory • mouse-up and keyboard events, if the currently active window belongs to a desk accessory Note: In each case, the event is intercepted by the Desk Manager only if the desk accessory can handle that type of event; however, as a rule all desk accessories should be set up to handle activate, update, and keyboard events and should not handle mouse-up events. The Desk Manager also intercepts disk-inserted events: It attempts to mount the volume on the disk by calling the File Manager function MountVol. GetNextEvent will always return TRUE in this case, though, so that your application can take any further appropriate action after examining the result code returned by MountVol in the event message. (See the Desk Manager and File Manager chapters.) GetNextEvent returns TRUE for all other non-null events (including all mouse-down events, regardless of which window is active), leaving them for your application to handle. GetNextEvent also makes the following processing happen, invisible to your program: • If the “alarm” is set and the current time is the alarm time, the alarm goes off (a beep followed by blinking the apple symbol in the menu bar). The user can set the alarm with the Alarm Clock desk accessory. • If the user holds down the Command and Shift keys while pressing a numeric key that has a special effect, that effect occurs. The standard such keys are 1 and 2 for ejecting the disk in the internal or external drive, and 3 and 4 for writing a snapshot of the screen to a MacPaint document or to the printer. Note: Advanced programmers can implement their own code to be executed in response to Command-Shift-number combinations (except for Command- Shift-1 and 2, which can’t be changed). The code corresponding to a particular number must be a routine having no parameters, stored in a resource whose type is 'FKEY' and whose ID is the number. The system resource file contains code for the numbers 3 and 4. Assembly-language note: You can disable GetNextEvent’s processing of Command- Shift-number combinations by setting the global variable ScrDmpEnb (a byte) to 0. æKY KeyMap æFp Events.p æT TYPE æC KeyMap = PACKED ARRAY [0..127] OF BOOLEAN; æKY mDownMask,mUpMask,keyDownMask,keyUpMask,autoKeyMask,updateMask,diskMask,activMask,networkMask,driverMask,app1Mask,app2Mask,app3Mask,app4Mask æFp Events.p æC _______________________________________________________________________________ »EVENT MASKS _______________________________________________________________________________ Some of the Event Manager routines can be restricted to operate on a specific event type or group of types; in other words, the specified event types are enabled while all others are disabled. For instance, instead of just requesting the next available event, you can specifically ask for the next keyboard event. You specify which event types a particular Event Manager call applies to by supplying an event mask as a parameter. This is an integer in which there’s one bit position for each event type, as shown in Figure 8. The bit position representing a given type corresponds to the event code for that type—for example, update events (event code 6) are specified by bit 6 of the mask. A 1 in bit 6 means that this Event Manager call applies to update events; a 0 means that it doesn’t. •••Refer to Figure 8.••• Figure 8–Event Mask Masks for each individual event type are available as predefined constants: CONST mDownMask = 2; {mouse-down} mUpMask = 4; {mouse-up} keyDownMask = 8; {key-down} keyUpMask = 16; {key-up} autoKeyMask = 32; {auto-key} updateMask = 64; {update} diskMask = 128; {disk-inserted} activMask = 256; {activate} networkMask = 1024; {network} driverMask = 2048; {device driver} app1Mask = 4096; {application-defined} app2Mask = 8192; {application-defined} app3Mask = 16384; {application-defined} app4Mask = -32768; {application-defined} Note: Null events can’t be disabled; a null event will always be reported when none of the enabled types of events are available. The following predefined mask designates all event types: CONST everyEvent = -1; {all event types} You can form any mask you need by adding or subtracting these mask constants. For example, to specify every keyboard event, use keyDownMask + keyUpMask + autoKeyMask For every event except an update, use everyEvent - updateMask Note: It’s recommended that you always use the event mask everyEvent unless there’s a specific reason not to. There’s also a global system event mask that controls which event types get posted into the event queue. Only event types corresponding to bits set in the system event mask are posted; all others are ignored. When the system starts up, the system event mask is set to post all except key-up event—that is, it’s initialized to everyEvent - keyUpMask Note: Key-up events are meaningless for most applications. Your application will usually want to ignore them; if not, it can set the system event mask with the Operating System Event Manager procedure SetEventMask. æKY nullEvent,mouseDown,mouseUp,keyDown,keyUp,autoKey,updateEvt,diskEvt,activateEvt,networkEvt,driverEvt,app1Evt,app2Evt,app3Evt,app4Evt æFp Events.p æC »Event Code The what field of an event record contains an event code identifying the type of the event. The event codes are available as predefined constants: CONST nullEvent = 0; {null} mouseDown = 1; {mouse-down} mouseUp = 2; {mouse-up} keyDown = 3; {key-down} keyUp = 4; {key-up} autoKey = 5; {auto-key} updateEvt = 6; {update} diskEvt = 7; {disk-inserted} activateEvt = 8; {activate} networkEvt = 10; {network} driverEvt = 11; {device driver} app1Evt = 12; {application-defined} app2Evt = 13; {application-defined} app3Evt = 14; {application-defined} app4Evt = 15; {application-defined} æKY StillDown æFp Events.p æT FUNCTION æTN $A973 æD FUNCTION StillDown: BOOLEAN; æDT myVariable := StillDown; æMM æRT 194 æRI StillDown function I-259 æC Usually called after a mouse-down event, StillDown tests whether the mouse button is still down. It returns TRUE if the button is currently down and there are no more mouse events pending in the event queue. This is a true test of whether the button is still down from the original press—unlike Button (above), which returns TRUE whenever the button is currently down, even if it has been released and pressed again since the original mouse-down event. æKY TickCount æFp Events.p æT FUNCTION æTN $A975 æD FUNCTION TickCount: LONGINT; æDT myVariable := TickCount; æMM æRI TickCount function I-260 æC TickCount returns the current number of ticks (sixtieths of a second) since the system last started up. Warning: Don’t rely on the tick count being exact; it will usually be accurate to within one tick, but may be off by more than that. The tick count is incremented during the vertical retrace interrupt, but it’s possible for this interrupt to be disabled. Furthermore, don’t rely on the tick count being incremented to a certain value, such as testing whether it has become equal to its old value plus 1; check instead for “greater than or equal to” (since an interrupt task may keep control for more than one tick). Assembly-language note: The value returned by this function is also contained in the global variable Ticks. æKY WaitMouseUp æFp Events.p æT FUNCTION æTN $A977 æD FUNCTION WaitMouseUp: BOOLEAN; æDT myVariable := WaitMouseUp; æMM æRT 194 æRI WaitMouseUp function I-259 æC WaitMouseUp works exactly the same as StillDown (above), except that if the button is not still down from the original press, WaitMouseUp removes the preceding mouse-up event before returning FALSE. If, for instance, your application attaches some special significance both to mouse double-clicks and to mouse-up events, this function would allow your application to recognize a double-click without being confused by the intervening mouse-up. æKY WaitNextEvent æFp Events.p æT FUNCTION æTN $A860 æD FUNCTION WaitNextEvent(mask: INTEGER;VAR event: EventRecord;sleep: LONGINT; mouseRgn: RgnHandle): BOOLEAN; æDT myVariable := WaitNextEvent(mask,event,sleep,mouseRgn); æRT 158, 177, 180, 194, 205 æRI WaitNextEvent N158-1 æKY Files.p æKL AddDrive Allocate AllocContig CatMove CloseWD Create DirCreate Eject FInitQueue FlushVol FSClose FSDelete FSOpen FSOpenFile FSRead FSWrite GetDrvQHdr GetEOF GetFInfo GetFPos GetFSQHdr GetVCBQHdr GetVInfo GetVol GetVRefNum GetWDInfo HCreate HDelete HGetFInfo HGetVol HOpen HOpenFile HOpenRF HRename HRstFLock HSetFInfo HSetFLock HSetVol OpenRF OpenWD PBAllocate PBAllocContig PBCatMove PBClose PBCloseWD PBCreate PBDelete PBDirCreate PBEject PBFlushFile PBFlushVol PBGetCatInfo PBGetEOF PBGetFCBInfo PBGetFInfo PBGetFPos PBGetVInfo PBGetVol PBGetWDInfo PBHCopyFile PBHCreate PBHDelete PBHGetDirAccess PBHGetFInfo PBHGetLogInInfo PBHGetVInfo PBHGetVol PBHGetVolParms PBHMapID PBHMapName PBHMoveRename PBHOpen PBHOpenDeny PBHOpenFile PBHOpenRF PBHOpenRFDeny PBHRename PBHRstFLock PBHSetDirAccess PBHSetFInfo PBHSetFLock PBHSetVol PBLockRange PBMountVol PBOffLine PBOpen PBOpenFile PBOpenRF PBOpenWD PBRead PBRename PBRstFLock PBSetCatInfo PBSetEOF PBSetFInfo PBSetFLock PBSetFPos PBSetFVers PBSetVInfo PBSetVol PBUnlockRange PBUnmountVol PBWrite Rename RstFLock SetEOF SetFInfo SetFLock SetFPos SetVol UnmountVol AccessParam alphaStage betaStage CInfoPBPtr CInfoPBRec CInfoType CMovePBPtr CMovePBRec CntrlParam CopyParam developStage DInfo dirInfo DXInfo FCBPBPtr FCBPBRec fDesktop fDisk fHasBundle FileParam finalStage FInfo fInvisible fOnDesk fsAtMark fsCurPerm fsFromLEOF fsFromMark fsFromStart fsRdPerm fsRdWrPerm fsRdWrShPerm fsRtDirID fsRtParID fsWrPerm fTrash FXInfo hFileInfo HParamBlockRec HParmBlkPtr ioDirFlg ioDirMask IOParam MultiDevParam NumVersion ObjParam ParamBlkType rdVerify SlotDevParam VCB VersRec VersRecHndl VersRecPtr VolumeParam WDParam WDPBPtr WDPBRec æKY VersRecHndl,VersRecPtr,VersRec æFp Files.p æT TYPE æC VersRecPtr = ^VersRec; VersRecHndl = ^VersRecPtr; VersRec = RECORD numericVersion: NumVersion; {encoded version number} countryCode: INTEGER; {country code from intl utilities} shortVersion: Str255; {version number string - worst case} reserved: Str255; {longMessage string packed after shortVersion} END; æKY WDPBRec,WDPBPtr æFp Files.p æT TYPE æC WDPBPtr = ^WDPBRec; WDPBRec = RECORD qLink: QElemPtr; qType: INTEGER; ioTrap: INTEGER; ioCmdAddr: Ptr; ioCompletion: ProcPtr; ioResult: OSErr; ioNamePtr: StringPtr; ioVRefNum: INTEGER; filler1: INTEGER; ioWDIndex: INTEGER; ioWDProcID: LONGINT; ioWDVRefNum: INTEGER; filler2: ARRAY [1..7] OF INTEGER; ioWDDirID: LONGINT; END; »WDPBRec When you call the routines that open, close, and get information about working directories, you’ll use the following six additional fields after the standard eight fields in the parameter block record WDPBRec: filler1: INTEGER; {not used} ioWDIndex: INTEGER; {index} ioWDProcID: LONGINT; {working directory user identifier} ioWDVRefNum: INTEGER; {working directory's volume reference number} filler2: ARRAY[1..7] OF INTEGER; {not used} ioWDDirID: LONGINT); {working directory's directory ID} IOWDIndex can be used with the function PBGetWDInfo to index through the current working directories. IOWDProcID is an identifier that’s used to distinguish between working directories set up by different users; you should use the application’s signature (discussed in the Finder Interface chapter) as the ioWDProcID. æKY ParamBlkType,IOParam,FileParam,VolumeParam,CntrlParam,SlotDevParam,MultiDevParam,AccessParam,ObjParam,CopyParam,WDParam æFp Files.p æC ParamBlkType = (IOParam,FileParam,VolumeParam,CntrlParam,SlotDevParam, MultiDevParam,AccessParam,ObjParam,CopyParam,WDParam); æKY HParamBlockRec,HParmBlkPtr æFp Files.p æT TYPE æC HParmBlkPtr = ^HParamBlockRec; HParamBlockRec = RECORD qLink: QElemPtr; qType: INTEGER; ioTrap: INTEGER; ioCmdAddr: Ptr; ioCompletion: ProcPtr; ioResult: OSErr; ioNamePtr: StringPtr; ioVRefNum: INTEGER; CASE ParamBlkType OF IOParam: (ioRefNum: INTEGER; ioVersNum: SignedByte; ioPermssn: SignedByte; ioMisc: Ptr; ioBuffer: Ptr; ioReqCount: LONGINT; {size of buffer area} ioActCount: LONGINT; {length of vol parms data} ioPosMode: INTEGER; ioPosOffset: LONGINT); FileParam: (ioFRefNum: INTEGER; ioFVersNum: SignedByte; filler1: SignedByte; ioFDirIndex: INTEGER; ioFlAttrib: SignedByte; ioFlVersNum: SignedByte; ioFlFndrInfo: FInfo; ioDirID: LONGINT; ioFlStBlk: INTEGER; ioFlLgLen: LONGINT; ioFlPyLen: LONGINT; ioFlRStBlk: INTEGER; ioFlRLgLen: LONGINT; ioFlRPyLen: LONGINT; ioFlCrDat: LONGINT; ioFlMdDat: LONGINT); VolumeParam: (filler2: LONGINT; ioVolIndex: INTEGER; ioVCrDate: LONGINT; ioVLsMod: LONGINT; ioVAtrb: INTEGER; ioVNmFls: INTEGER; ioVBitMap: INTEGER; ioAllocPtr: INTEGER; ioVNmAlBlks: INTEGER; ioVAlBlkSiz: LONGINT; ioVClpSiz: LONGINT; ioAlBlSt: INTEGER; ioVNxtCNID: LONGINT; ioVFrBlk: INTEGER; ioVSigWord: INTEGER; ioVDrvInfo: INTEGER; ioVDRefNum: INTEGER; ioVFSID: INTEGER; ioVBkUp: LONGINT; ioVSeqNum: INTEGER; ioVWrCnt: LONGINT; ioVFilCnt: LONGINT; ioVDirCnt: LONGINT; ioVFndrInfo: ARRAY [1..8] OF LONGINT); AccessParam: (filler3: INTEGER; ioDenyModes: INTEGER; {access rights data} filler4: INTEGER; filler5: SignedByte; ioACUser: SignedByte; {access rights for directory only} filler6: LONGINT; ioACOwnerID: LONGINT; {owner ID} ioACGroupID: LONGINT; {group ID} ioACAccess: LONGINT); {access rights} ObjParam: (filler7: INTEGER; ioObjType: INTEGER; {function code} ioObjNamePtr: Ptr; {ptr to returned creator/group name} ioObjID: LONGINT); {creator/group ID} CopyParam: (ioDstVRefNum: INTEGER; {destination vol identifier} filler8: INTEGER; ioNewName: Ptr; {ptr to destination pathname} ioCopyName: Ptr; {ptr to optional name} ioNewDirID: LONGINT); {destination directory ID} WDParam: (filler9: INTEGER; ioWDIndex: INTEGER; ioWDProcID: LONGINT; ioWDVRefNum: INTEGER; filler10: INTEGER; filler11: LONGINT; filler12: LONGINT; filler13: LONGINT; ioWDDirID: LONGINT); END; »FileParam Variant ( ParamBlockRec and HParamBlockRec) The fileParam variants of ParamBlockRec and HParamBlockRec are identical, with one exception: The field ioDirID in HParamBlockRec is called ioFlNum in ParamBlockRec. The fields of the fileParam variant of HParamBlockRec are as follows: •••Refer to Technical Note #204:••• fileParam: (ioFRefNum: INTEGER; {path reference number} ioFVersNum: SignedByte; {version number} filler1: SignedByte; {not used} ioFDirIndex: INTEGER; {index} ioFlAttrib: SignedByte; {file attributes} ioFlVersNum: SignedByte; {version number} ioFlFndrInfo: FInfo; {information used by the Finder} ioDirID: LONGINT; {directory ID or file number} ioFlStBlk: INTEGER; {first allocation block of data fork} ioFlLgLen: LONGINT; {logical end-of-file of data fork} ioFlPyLen: LONGINT; {physical end-of-file of data fork} ioFlRStBlk: INTEGER; {first allocation block of resource fork} ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} ioFlRPyLen: LONGINT; {physical end-of-file of resource fork} ioFlCrDat: LONGINT; {date and time of creation} ioFlMdDat: LONGINT); {date and time of last modification} IOFDirIndex can be used with the PBGetFInfo and PBHGetFInfo to index through the files in a given directory. Warning: When used with GetFileInfo, ioFDirIndex will index only the files in a directory. To index both files and directories, you can use ioFDirIndex with PBGetCatInfo. IOFlAttrib contains the following file attributes: Bit Meaning 0 Set if file is locked 2 Set if resource fork is open 3 Set if data fork is open 4 Set if a directory 7 Set if file (either fork) is open When passed to a routine, ioDirID contains a directory ID; it can be used to refer to a directory or, in conjuction with a partial pathname from that directory, to other files and directories. If both a directory ID and a working directory reference number are provided, the directory ID is used to identify the directory on the volume indicated by the working directory reference number. In other words, a directory ID specified by the caller will override the working directory referred to by the working directory reference number. If you don’t want this to happen, you can set ioDirID to 0. (If no directory is specified through a working directory reference number, the root directory ID will be used.) When returned from a routine, ioDirID contains the file number of a file; most programmers needn’t be concerned with file numbers, but those interested can read the section “Data Organization on Volumes”. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty, respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat and ioFlMdDat fields are specified in seconds since midnight, January 1, 1904. »VolumeParam Variant (ParamBlockRec) When you call GetVolInfo, you’ll use the volumeParam variant of ParamBlockRec: volumeParam: (filler2: LONGINT; {not used} ioVolIndex: INTEGER; {index} ioVCrDate: LONGINT; {date and time of initialization} ioVLsBkUp: LONGINT; {date and time of last modification} ioVAtrb: INTEGER; {volume attributes} ioVNmFls: INTEGER; {number of files in root directory} ioVDirSt: INTEGER; {first block of directory} ioVBlLn: INTEGER; {length of directory in blocks} ioVNmAlBlks: INTEGER; {number of allocation blocks} ioVAlBlkSiz: LONGINT; {size of allocation blocks} ioVClpSiz: LONGINT; {number of bytes to allocate} ioAlBlSt: INTEGER; {first block in volume block map} ioVNxtFNum: LONGINT; {next unused file number} ioVFrBlk: INTEGER); {number of unused allocation blocks} IOVolIndex can be used to index through all the mounted volumes; using an index of 1 accesses the first volume mounted, and so on. (For more information on indexing, see the section “Indexing” above.) IOVLsBkUp contains the date and time the volume information was last modified (this is not necessarily when it was flushed). (This field is not modified when information is written to a file.) Note: The name ioVLsBkUp is actually a misnomer; this field has always contained the date and time of the last modification to the volume, not the last backup. Most programmers needn’t be concerned with the remaining parameters, but interested programmers can read the section “Data Organization on Volumes”. »VolumeParam Variant (HParamBlockRec) When you call HGetVInfo and SetVolInfo, you’ll use the volumeParam variant of HParamBlockRec. This is a superset of the volumeParam variant of ParamBlockRec; the names and functions of certain fields have been changed, and new fields have been added: volumeParam: (filler2: LONGINT; {not used} ioVolIndex: INTEGER; {index} ioVCrDate: LONGINT; {date and time of initialization} ioVLsMod: LONGINT; {date and time of last modification} ioVAtrb: INTEGER; {volume attributes} ioVNmFls: INTEGER; {number of files in root directory} ioVBitMap: INTEGER; {first block of volume bit map} ioAllocPtr: INTEGER; {block at which next new file starts} ioVNmAlBlks: INTEGER; {number of allocation blocks} ioVAlBlkSiz: LONGINT; {size of allocation blocks} ioVClpSiz: LONGINT; {number of bytes to allocate} ioAlBlSt: INTEGER; {first block in volume block map} ioVNxtCNID: LONGINT; {next unused file number} ioVFrBlk: INTEGER; {number of unused allocation blocks} ioVSigWord: INTEGER; {volume signature} ioVDrvInfo: INTEGER; {drive number} ioVDRefNum: INTEGER; {driver reference number} ioVFSID: INTEGER; {file system handling this volume} ioVBkUp: LONGINT; {date and time of last backup} ioVSeqNum: INTEGER; {used internally} ioVWrCnt LONGINT; {volume write count} ioVFilCnt: LONGINT; {number of files on volume} ioVDirCnt: LONGINT; {number of directories on volume} ioVFndrInfo: ARRAY[1..8] OF LONGINT); {information used by the Finder} IOVolIndex can be used to index through all the mounted volumes; using an index of 1 accesses the first volume mounted, and so on. (For more information on indexing, see the section “Indexing” above.) IOVLsMod contains the date and time the volume information was last modified (this is not necessarily when it was flushed). (This field is not modified when information is written to a file.) Note: IOVLsMod replaces the field ioVLsBkUp in ParamBlockRec. The name ioVLsBkUp was actually a misnomer; this field has always contained the date and time of the last modification, not the last backup. Another field, ioVBkUp, contains the date and time of the last backup. IOVClpSiz can be used to set the volume clump size in bytes; it’s used for files that don’t have a clump size defined as part of their file information in the catalog. To promote file contiguity and avoid fragmentation, space is allocated to a file not in allocation blocks but in clumps. A clump is a group of contiguous allocation blocks. The clump size is always a multiple of the allocation block size; it’s the minimum number of bytes to allocate each time the Allocate function is called or the end-of-file is reached during the Write routine. IOVSigWord contains a signature word identifying the type of volume; it’s $D2D7 for flat directory volumes and $4244 for hierarchical directory volumes. The drive number of the drive containing the volume is returned in ioDrvInfo. For on-line volumes, ioVDRefNum returns the reference number of the I/O driver for the drive identified by ioDrvInfo. IOVFSID is the file-system identifier. It indicates which file system is servicing the volume; it’s 0 for File Manager volumes and nonzero for volumes handled by an external file system. IOVBkUp specifies the date and time the volume was last backed up (it’s 0 if never backed up). IOVNmFls contains the number of files in the root directory. IOVFilCnt contains the total number of files on the volume, while ioVDirCnt contains the total number of directories (not including the root directory). Most programmers needn’t be concerned with the other parameters, but interested programmers can read the section “Data Organization on Volumes”. HParamBlockRec, described above, has been extended to support a shared environment with the addition of AccessParam, ObjParam, CopyParam, and WDParam, as shown below. (The complete HParamBlockRec data type is shown in the summary.) AccessParam: (filler3: INTEGER; ioDenyModes: INTEGER; {access rights data} filler4: INTEGER; filler5: Signed Byte; ioACUser: Signed Byte; {access rights for directory only} filler6: LONGINT; ioACOwnerID: LONGINT; {owner ID} ioACGroupID: LONGINT; {group ID} ioACAccess: LONGINT); {access rights} ObjParam: (filler7: INTEGER; ioObjType: INTEGER; {function code} ioObjNamePtr: Ptr; {ptr to returned creator/group name} ioObjID: LONGINT; {creator/group ID} ioReqCount: LONGINT; {size of buffer area} ioActCount: LONGINT); {length of vol parms data} CopyParam: (ioDstVRefNum: INTEGER; {destination vol identifier} filler8: INTEGER; ioNewName: Ptr; {ptr to destination pathname} ioCopyName: Ptr; {ptr to optional name} ioNewDirID: LONGINT); {destination directory ID} WDParam: (filler9: INTEGER; ioWDIndex: INTEGER; ioWDProcID: LONGINT; ioWDVRefNum: INTEGER; filler10: INTEGER; filler11: LONGINT; filler12: LONGINT; filler13: LONGINT; ioWDDirID: LONGINT); æKY FCBPBPtr,FCBPBRec æFp Files.p æT TYPE æC FCBPBPtr = ^FCBPBRec; FCBPBRec = RECORD qLink: QElemPtr; qType: INTEGER; ioTrap: INTEGER; ioCmdAddr: Ptr; ioCompletion: ProcPtr; ioResult: OSErr; ioNamePtr: StringPtr; ioVRefNum: INTEGER; ioRefNum: INTEGER; filler: INTEGER; ioFCBIndx: INTEGER; filler1: INTEGER; ioFCBFlNm: LONGINT; ioFCBFlags: INTEGER; ioFCBStBlk: INTEGER; ioFCBEOF: LONGINT; ioFCBPLen: LONGINT; ioFCBCrPs: LONGINT; ioFCBVRefNum: INTEGER; ioFCBClpSiz: LONGINT; ioFCBParID: LONGINT; END; æKY CInfoType,hFileInfo,dirInfo æFp Files.p æC CInfoType = (hFileInfo,dirInfo); æKY AddDrive æFp Files.p æT PROCEDURE æTN $A04E æD PROCEDURE AddDrive(drvrRefNum: INTEGER;drvNum: INTEGER;qEl: DrvQElPtr); æDT AddDrive(drvrRefNum,drvNum,qEl); æRT 36, 108 æRI AddDrive function N36, N108-1 æKY Allocate æFp Files.p æT FUNCTION æTN $A010 æD FUNCTION Allocate(refNum: INTEGER;VAR count: LONGINT): OSErr; æDT myVariable := Allocate(refNum,count); æRI Allocate function high-level IV-112 low-level IV-143 æC [Not in ROM] Allocate adds the number of bytes specified by the count parameter to the open file whose access path is specified by refNum, and sets the physical end-of-file to one byte beyond the last block allocated. The number of bytes actually allocated is rounded up to the nearest multiple of the allocation block size, and returned in the count parameter. If there isn’t enough empty space on the volume to satisfy the allocation request, Allocate allocates the rest of the space on the volume and returns dskFulErr as its function result. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY AllocContig æFp Files.p æT FUNCTION æD FUNCTION AllocContig(refNum: INTEGER;VAR count: LONGINT): OSErr; æDT myVariable := AllocContig(refNum,count); æRT 218 æRI AllocContig function IV-143 high-level IV-112 low-level IV-143 æKY alphaStage æFp Files.p æC alphaStage = $40; æKY betaStage æFp Files.p æC betaStage = $60; æKY CatMove æFp Files.p æT FUNCTION æTN $A260 æD FUNCTION CatMove(vRefNum: INTEGER;dirID: LONGINT;oldName: Str255;newDirID: LONGINT; newName: Str255): OSErr; æDT myVariable := CatMove(vRefNum,dirID,oldName,newDirID,newName); æRT 218 æRI CatMove function IV-157 æKY CInfoPBRec,CInfoPBPtr æFp Files.p æT TYPE æC CInfoPBPtr = ^CInfoPBRec; CInfoPBRec = RECORD qLink: QElemPtr; qType: INTEGER; ioTrap: INTEGER; ioCmdAddr: Ptr; ioCompletion: ProcPtr; ioResult: OSErr; ioNamePtr: StringPtr; ioVRefNum: INTEGER; ioFRefNum: INTEGER; ioFVersNum: SignedByte; filler1: SignedByte; ioFDirIndex: INTEGER; ioFlAttrib: SignedByte; filler2: SignedByte; CASE CInfoType OF hFileInfo: (ioFlFndrInfo: FInfo; ioDirID: LONGINT; ioFlStBlk: INTEGER; ioFlLgLen: LONGINT; ioFlPyLen: LONGINT; ioFlRStBlk: INTEGER; ioFlRLgLen: LONGINT; ioFlRPyLen: LONGINT; ioFlCrDat: LONGINT; ioFlMdDat: LONGINT; ioFlBkDat: LONGINT; ioFlXFndrInfo: FXInfo; ioFlParID: LONGINT; ioFlClpSiz: LONGINT); dirInfo: (ioDrUsrWds: DInfo; ioDrDirID: LONGINT; ioDrNmFls: INTEGER; filler3: ARRAY [1..9] OF INTEGER; ioDrCrDat: LONGINT; ioDrMdDat: LONGINT; ioDrBkDat: LONGINT; ioDrFndrInfo: DXInfo; ioDrParID: LONGINT); END; »CInfoPBRec The routines GetCatInfo and SetCatInfo are used for getting and setting information about the files and directories within a directory. With files, you’ll use the following 19 additional fields after the standard eight fields in the parameter block record CInfoPBRec: ioFRefNum: INTEGER; {path reference number} ioFVersNum: SignedByte; {version number} filler1: SignedByte; {not used} ioFDirIndex: INTEGER; {index} ioFlAttrib: SignedByte; {file attributes} filler2: SignedByte; {not used} hFileInfo: (ioFlFndrInfo: FInfo; {information used by the Finder} ioDirID: LONGINT; {directory ID or file number} ioFlStBlk: INTEGER; {first allocation block of data fork} ioFlLgLen: LONGINT; {logical end-of-file of data fork} ioFlPyLen: LONGINT; {physical end-of-file of data fork} ioFlRStBlk: INTEGER; {first allocation block of resource fork} ioFlRLgLen: LONGINT; {logical end-of-file of resource fork} ioFlRPyLen: LONGINT; {physical end-of-file of resource fork} ioFlCrDat: LONGINT; {date and time of creation} ioFlMdDat: LONGINT; {date and time of last modification} ioFlBkDat: LONGINT; {date and time of last backup} ioFlXFndrInfo: FXInfo; {additional information used by the Finder} ioFlParID: LONGINT; {file's parent directory ID (integer)} ioFlClpSiz: LONGINT); {file's clump size} •••Refer to Technical Note #69:••• IOFDirIndex can be used with the function PBGetCatInfo to index through the files and directories in a given directory. For each iteration of the function, you can determine whether it’s a file or a directory by testing bit 4 (the fifth least significant bit) of ioFlAttrib. You can test for a directory by using the Toolbox Utilities BitTst function in the following manner (remember, the Toolbox Utilities routines reverse the standard 68000 notation): BitTst(@myCInfoRec.ioFlAttrib,3) IOFlAttrib contains the following attributes: Bit Meaning 0 Set if file is locked 2 Set if resource fork is open 3 Set if data fork is open 4 Set if a directory 7 Set if file (either fork) is open When passed to a routine, ioDirID contains a directory ID; it can be used to refer to a directory or, in conjuction with a partial pathname from that directory, to other files and directories. If both a directory ID and a working directory reference number are provided, the directory ID is used to identify the directory on the volume indicated by the working directory reference number. In other words, a directory ID specified by the caller will override the working directory referred to by the working directory reference number. If you don’t want this to happen, you can set ioDirID to 0. (If no directory is specified through a working directory reference number, the root directory ID will be used.) Warning: With files, ioDirID returns the file number of the file; when indexing with GetCatInfo, you’ll need to reset this field for each iteration. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty, respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat, ioFlMdDat, and ioFlBkDat fields are specified in seconds since midnight, January 1, 1904. IOFlParID contains the directory ID of the file’s parent. IOFlClpSiz is the clump size to be used when writing the file; if it’s 0, the volume’s clump size is used when the file is opened. With directories, you’ll use the following 14 additional fields after the standard eight fields in the parameter block record CInfoPBRec: ioFRefNum: INTEGER; {file reference number} ioFVersNum SignedByte; {version number} filler1: SignedByte; {not used} ioFDirIndex: INTEGER; {index} ioFlAttrib: SignedByte; {file attributes} filler2: SignedByte; {not used} dirInfo: (ioDrUsrWds: DInfo; {information used by the Finder} ioDrDirID: LONGINT; {directory ID} ioDrNmFls: INTEGER; {number of files in directory} filler3: ARRAY[1..9] OF INTEGER; {not used} ioDrCrDat: LONGINT; {date and time of creation} ioDrMdDat: LONGINT; {date and time of last modification} ioDrBkDat: LONGINT; {date and time of last backup} ioDrFndrInfo: DXInfo; {additional information used by the Finder} ioDrParID: LONGINT); {directory's parent directory ID (integer)} IOFDirIndex can be used with the function PBGetCatInfo to index through the files and directories in a given directory. For each iteration of the function, you can determine whether it’s a file or a directory by testing bit 4 of ioFlAttrib. When passed to a routine, ioDrDirID contains a directory ID; it can be used to refer to a directory or, in conjuction with a partial pathname from that directory, to other files and directories. If both a directory ID and a working directory reference number are provided, the directory ID is used to identify the directory on the volume indicated by the working directory reference number. In other words, a directory ID specified by the caller will override the working directory referred to by the working directory reference number. If you don’t want this to happen, you can set ioDirID to 0. (If no directory is specified through a working directory reference number, the root directory ID will be used.) With directories, ioDrDirID returns the directory ID of the directory. IODrNmFls is the number of files and directories contained in this directory (the valence of the directory). The date and time in the ioDrCrDat, ioDrMdDat, and ioDrBkDat fields are specified in seconds since midnight, January 1, 1904. IODrParID contains the directory ID of the directory’s parent. æKY CloseWD æFp Files.p æT FUNCTION æTN $A260 æD FUNCTION CloseWD(wdRefNum: INTEGER): OSErr; æDT myVariable := CloseWD(wdRefNum); æRT 218 æRI CloseWD function IV-158 æKY CMovePBRec,CMovePBPtr æFp Files.p æT TYPE æC CMovePBPtr = ^CMovePBRec; CMovePBRec = RECORD qLink: QElemPtr; qType: INTEGER; ioTrap: INTEGER; ioCmdAddr: Ptr; ioCompletion: ProcPtr; ioResult: OSErr; ioNamePtr: StringPtr; ioVRefNum: INTEGER; filler1: LONGINT; ioNewName: StringPtr; filler2: LONGINT; ioNewDirID: LONGINT; filler3: ARRAY [1..2] OF LONGINT; ioDirID: LONGINT; END; »CMovePBRec When you call CatMove to move files or directories into a different directory, you’ll use the following six additional fields after the standard eight fields in the parameter block record CMovePBRec: filler1: LONGINT; {not used} ioNewName: StringPtr; {name of new directory} filler2: LONGINT; {not used} ioNewDirID: LONGINT; {directory ID of new directory} filler3: ARRAY[1..2] OF LONGINT; {not used} ioDirID: LONGINT); {directory ID of current directory} IONewName and ioNewDirID specify the name and directory ID of the directory to which the file or directory is to be moved. IODirID (used in conjuntion with the ioVRefNum and ioNamePtr) specifies the current directory ID of the file or directory to be moved. æKY Create æFp Files.p æT FUNCTION æTN $A008 æD FUNCTION Create(fileName: Str255;vRefNum: INTEGER;creator: OSType;fileType: OSType): OSErr; æDT myVariable := Create(fileName,vRefNum,creator,fileType); æRI Create function high-level II-90, IV-112 low-level II-107, IV-145 æC [Not in ROM] Create creates a new file (both forks) with the specified name, file type, and creator on the specified volume. (File type and creator are discussed in the Finder Interface chapter.) The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY developStage æFp Files.p æC developStage = $20; æKY DInfo æFp Files.p æT RECORD æC DInfo = RECORD frRect: Rect; {folder rect} frFlags: INTEGER; {Flags} frLocation: Point; {folder location} frView: INTEGER; {folder view} END; On hierarchical volumes, the following information about directories is maintained for the Finder: DInfo = RECORD frRect: Rect; {folder's rectangle} frFlags: INTEGER; {flags} frLocation: Point; {folder's location} frView: INTEGER; {folder's view} END; DXInfo = RECORD frScroll: Point; {scroll position} frOpenChain: LONGINT; {directory ID chain of open folders} frUnused: INTEGER; {reserved} frComment: INTEGER; {comment ID} frPutAway: LONGINT; {directory ID} END; When a file (or folder) is moved to the desktop on a hierarchical volume, it’s actually moved to the root level of the file directory. (This permits all the desktop icons to be enumerated by one simple scan of the root.) The fOnDesk bit of fdFlags is set. FDPutAway (or frPutAway for directories) contains the directory ID of the folder that originally contained the file (or folder); this allows the file (or folder) to be returned there from the desktop. æKY DirCreate æFp Files.p æT FUNCTION æTN $A260 æD FUNCTION DirCreate(vRefNum: INTEGER;parentDirID: LONGINT;directoryName: Str255; VAR createdDirID: LONGINT): OSErr; æDT myVariable := DirCreate(vRefNum,parentDirID,directoryName,createdDirID); æRT 218 æRI DirCreate function IV-146 æKY DXInfo æFp Files.p æT RECORD æC DXInfo = RECORD frScroll: Point; {scroll position} frOpenChain: LONGINT; {DirID chain of open folders} frUnused: INTEGER; {unused but reserved} frComment: INTEGER; {comment} frPutAway: LONGINT; {DirID} END; æKY Eject æFp Files.p æT FUNCTION æTN $A017 æD FUNCTION Eject(volName: StringPtr;vRefNum: INTEGER): OSErr; æDT myVariable := Eject(volName,vRefNum); æMM æRI Eject function high-level II-90, IV-108 low-level II-107, IV-135 æC [Not in ROM] Eject flushes the volume specified by volName or vRefNum, places it off-line, and then ejects the volume. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume paramErr No default volume æKY finalStage æFp Files.p æC finalStage = $80; æKY FInfo æFp Files.p æT RECORD æC FInfo = RECORD fdType: OSType; {the type of the file} fdCreator: OSType; {file's creator} fdFlags: INTEGER; {flags ex. hasbundle,invisible,locked, etc.} fdLocation: Point; {file's location in folder} fdFldr: INTEGER; {folder containing file} END; æKY FInitQueue æFp Files.p æT PROCEDURE æTN $A016 æD PROCEDURE FInitQueue; æDT FInitQueue; æRI FInitQueue procedure II-103, IV-128 æC Trap macro _InitQueue FInitQueue clears all queued File Manager calls except the current one. æKY FlushVol æFp Files.p æT FUNCTION æTN $A013 æD FUNCTION FlushVol(volName: StringPtr;vRefNum: INTEGER): OSErr; æDT myVariable := FlushVol(volName,vRefNum); æMM æRI FlushVol function P-132, 133 high-level II-89, IV-108 low-level II-105, IV-133 æC [Not in ROM] On the volume specified by volName or vRefNum, FlushVol writes the contents of the associated volume buffer and descriptive information about the volume (if they’ve changed since the last time FlushVol was called). Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY fOnDesk,fHasBundle,fInvisible,fTrash,fDesktop,fDisk æFp Files.p æC { Flags in file information used by the Finder } fOnDesk = 1; {set if file is on desktop (hierarchical volumes only)} fHasBundle = 8192; {set if file has a bundle} fInvisible = 16384; {set if file's icon is invisible} fTrash = -3; {file is in Trash window} fDesktop = -2; {file is on desktop} fDisk = 0; {file is in disk window} æKY fsAtMark,fsFromStart,fsFromLEOF,fsFromMark æFp Files.p æC IOPosMode and ioPosOffset specify the position of the mark for Read, Write, LockRng, UnlockRng, and SetFPos calls. IOPosMode contains the positioning mode; bits 0 and 1 indicate how to position the mark, and you can use the following predefined constants to set or test their value: CONST fsAtMark = 0; {at current mark} fsFromStart = 1; {set mark relative to beginning of file} fsFromLEOF = 2; {set mark relative to logical end-of-file} fsFromMark = 3; {set mark relative to current mark} If you specify fsAtMark, ioPosOffset is ignored and the operation begins wherever the mark is currently positioned. If you choose to set the mark (relative to either the beginning of the file, the logical end-of-file, or the current mark), ioPosOffset must specify the byte offset from the chosen point (either positive or negative) where the operation should begin. Note: Advanced programmers: Bit 7 of ioPosMode is the newline flag; it’s set if read operations should terminate at a newline character. The ASCII code of the newline character is specified in the high-order byte of ioPosMode. If the newline flag is set, the data will be read one byte at a time until the newline character is encountered, ioReqCount bytes have been read, or the end-of-file is reached. If the newline flag is clear, the data will be read one byte at a time until ioReqCount bytes have been read or the end-of-file is reached. æKY FSClose æFp Files.p æT FUNCTION æD FUNCTION FSClose(refNum: INTEGER): OSErr; æDT myVariable := FSClose(refNum); æRT 102 æRI FSClose function II-94, IV-112, P-132, 133, 171 æC [Not in ROM] FSClose removes the access path specified by refNum, writes the contents of the volume buffer to the volume, and updates the file’s entry in the file directory. Note: There’s no guarantee that any bytes have been written until FlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY fsCurPerm,fsRdPerm,fsWrPerm,fsRdWrPerm,fsRdWrShPerm æFp Files.p æC IOPermssn requests permission to read or write via an access path, and must contain one of the following values: CONST fsCurPerm = 0; {whatever is currently allowed} fsRdPerm = 1; {request for read permission only} fsWrPerm = 2; {request for write permission} fsRdWrPerm = 3; {request for exclusive read/write permission} fsRdWrShPerm = 4; {request for shared read/write permission} This request is compared with the open permission of the file. If the open permission doesn’t allow I/O as requested, a result code indicating the error is returned. Warning: To ensure data integrity be sure to lock the portion of the file you’ll be using if you specify shared write permission. æKY FSDelete æFp Files.p æT FUNCTION æD FUNCTION FSDelete(fileName: Str255;vRefNum: INTEGER): OSErr; æDT myVariable := FSDelete(fileName,vRefNum); æRI FSDelete function II-97, IV-113 æC [Not in ROM] FSDelete removes the closed file having the name fileName from the specified volume. Note: This function will delete both forks of a file. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fBsyErr File busy fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY FSOpen æFp Files.p æT FUNCTION æD FUNCTION FSOpen(fileName: Str255;vRefNum: INTEGER;VAR refNum: INTEGER): OSErr; æDT myVariable := FSOpen(fileName,vRefNum,refNum); æRT 102 æRI FSOpen function II-91, IV-109, P-131, 171 æC [Not in ROM] FSOpen creates an access path to the file having the name fileName on the volume specified by vRefNum. A path reference number is returned in refNum. The access path’s read/write permission is set to whatever the file’s open permission allows. Note: There’s no guarantee that any bytes have been written until FlushVol is called. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing tmfoErr Too many files open æKY FSOpenFile æFp Files.p æT FUNCTION æD FUNCTION FSOpenFile(vRefNum: INTEGER;fileName: Str255;permission: SignedByte; VAR refNum: INTEGER): OSErr; æDT myVariable := FSOpenFile(vRefNum,fileName,permission,refNum); æRT 102 æRI FSOpen function IV-109 æKY FSRead æFp Files.p æT FUNCTION æD FUNCTION FSRead(refNum: INTEGER;VAR count: LONGINT;buffPtr: Ptr): OSErr; æDT myVariable := FSRead(refNum,count,buffPtr); æRI FSRead function IV-109, P-131, 171 æC [Not in ROM] FSRead attempts to read the number of bytes specified by the count parameter from the open file whose access path is specified by refNum, and transfer them to the data buffer pointed to by buffPtr. The read operation begins at the current mark, so you might want to precede this with a call to SetFPos. If you try to read past the logical end-of-file, FSRead moves the mark to the end-of-file and returns eofErr as its function result. After the read is completed, the number of bytes actually read is returned in the count parameter. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative count rfNumErr Bad reference number æKY fsRtDirID æFp Files.p æC fsRtDirID = 2; æKY fsRtParID æFp Files.p æC fsRtParID = 1; æKY FSWrite æFp Files.p æT FUNCTION æD FUNCTION FSWrite(refNum: INTEGER;VAR count: LONGINT;buffPtr: Ptr): OSErr; æDT myVariable := FSWrite(refNum,count,buffPtr); æRI FSWrite function IV-110, P-132, 171 æC [Not in ROM] FSWrite takes the number of bytes specified by the count parameter from the buffer pointed to by buffPtr and attempts to write them to the open file whose access path is specified by refNum. The write operation begins at the current mark, so you might want to precede this with a call to SetFPos. After the write is completed, the number of bytes actually written is returned in the count parameter. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error paramErr Negative count rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY FXInfo æFp Files.p æT RECORD æC FXInfo = RECORD fdIconID: INTEGER; {Icon ID} fdUnused: ARRAY [1..4] OF INTEGER; {unused but reserved 8 bytes} fdComment: INTEGER; {Comment ID} fdPutAway: LONGINT; {Home Dir ID} END; On hierarchical volumes, in addition to the FInfo record, the following information about files is maintained for the Finder: æKY GetDrvQHdr æFp Files.p æT FUNCTION æD FUNCTION GetDrvQHdr: QHdrPtr; æDT myVariable := GetDrvQHdr; æRI GetDrvQHdr function II-128, IV-181 æC You can get a pointer to the header of the drive queue by calling the File Manager function GetDrvQHdr. FUNCTION GetDrvQHdr : QHdrPtr; [Not in ROM] GetDrvQHdr returns a pointer to the header of the drive queue. Assembly-language note: The global variable DrvQHdr contains the header of the drive queue. The drive queue can support any number of drives, limited only by memory space. æKY GetEOF æFp Files.p æT FUNCTION æTN $A011 æD FUNCTION GetEOF(refNum: INTEGER;VAR logEOF: LONGINT): OSErr; æDT myVariable := GetEOF(refNum,logEOF); æRI GetEOF function P-132, 172 high-level II-93, IV-111 low-level II-112, IV-142 æC [Not in ROM] GetEOF returns, in logEOF, the logical end-of-file of the open file whose access path is specified by refNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY GetFInfo æFp Files.p æT FUNCTION æD FUNCTION GetFInfo(fileName: Str255;vRefNum: INTEGER;VAR fndrInfo: FInfo): OSErr; æDT myVariable := GetFInfo(fileName,vRefNum,fndrInfo); æRI GetFInfo function II-95, IV-113 æC [Not in ROM] For the file having the name fileName on the specified volume, GetFInfo returns information used by the Finder in fndrInfo (see the section “Information Used by the Finder”). Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY GetFPos æFp Files.p æT FUNCTION æTN $A018 æD FUNCTION GetFPos(refNum: INTEGER;VAR filePos: LONGINT): OSErr; æDT myVariable := GetFPos(refNum,filePos); æRI GetFPos function P-132 high-level II-92, IV-110 low-level II-111, IV-141 æC [Not in ROM] GetFPos returns, in filePos, the mark of the open file whose access path is specified by refNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY GetFSQHdr æFp Files.p æT FUNCTION æD FUNCTION GetFSQHdr: QHdrPtr; æDT myVariable := GetFSQHdr; æRI GetFSQHdr function II-125, IV-175 æC You can get a pointer to the header of the file I/O queue by calling the File Manager function GetFSQHdr. FUNCTION GetFSQHdr : QHdrPtr; [Not in ROM] GetFSQHdr returns a pointer to the header of the file I/O queue. Assembly-language note: The global variable FSQHdr contains the header of the file I/O queue. æKY GetVCBQHdr æFp Files.p æT FUNCTION æD FUNCTION GetVCBQHdr: QHdrPtr; æDT myVariable := GetVCBQHdr; æRI GetVCBQHdr function II-126, IV-178 æC You can get a pointer to the header of the volume-control-block queue by calling the File Manager function GetVCBQHdr. FUNCTION GetVCBQHdr : QHdrPtr; [Not in ROM] GetVCBQHdr returns a pointer to the header of the volume-control-block queue. Assembly-language note: The global variable VCBQHdr contains the header of the volume-control-block-queue. The default volume’s volume control block is pointed to by the global variable DefVCBPtr. æKY GetVInfo æFp Files.p æT FUNCTION æD FUNCTION GetVInfo(drvNum: INTEGER;volName: StringPtr;VAR vRefNum: INTEGER; VAR freeBytes: LONGINT): OSErr; æDT myVariable := GetVInfo(drvNum,volName,vRefNum,freeBytes); æRT 157 æRI GetVInfo function II-89, IV-107, N157, low-level II-104, IV-129 æC »Accessing Volumes •••Refer to Technical Note #24:••• FUNCTION GetVInfo (drvNum: INTEGER; volName: StringPtr; VAR vRefNum: INTEGER; VAR freeBytes: LONGINT) : OSErr; [Not in ROM] •••Refer to Technical Note #157:••• GetVInfo returns the name, reference number, and available space (in bytes), in volName, vRefNum, and freeBytes, for the volume in the drive specified by drvNum. Result codes noErr No error nsvErr No default volume paramErr Bad drive number æKY GetVol æFp Files.p æT FUNCTION æTN $A014 æD FUNCTION GetVol(volName: StringPtr;VAR vRefNum: INTEGER): OSErr; æDT myVariable := GetVol(volName,vRefNum); æRT 77,140 æRI GetVol function N77-2, N140 high-level II-89, IV-107 low-level II-104, IV-131 æC [Not in ROM] GetVol returns the name of the default volume in volName and its volume reference number in vRefNum. Result codes noErr No error nsvErr No such volume æKY GetVRefNum æFp Files.p æT FUNCTION æD FUNCTION GetVRefNum(fileRefNum: INTEGER;VAR vRefNum: INTEGER): OSErr; æDT myVariable := GetVRefNum(fileRefNum,vRefNum); æRI GetVRefNum function II-89, IV-107 æC [Not in ROM] Given a path reference number in pathRefNum, GetVRefNum returns the volume reference number in vRefNum. Result codes noErr No error rfNumErr Bad reference number æKY GetWDInfo æFp Files.p æT FUNCTION æTN $A260 æD FUNCTION GetWDInfo(wdRefNum: INTEGER;VAR vRefNum: INTEGER;VAR dirID: LONGINT; VAR procID: LONGINT): OSErr; æDT myVariable := GetWDInfo(wdRefNum,vRefNum,dirID,procID); æRT 218 æRI GetWDInfo function IV-159 æKY HCreate æFp Files.p æT FUNCTION æD FUNCTION HCreate(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255;creator: OSType; fileType: OSType): OSErr; æDT myVariable := HCreate(vRefNum,dirID,fileName,creator,fileType); æRT 218 æRI HCreate function IV-146 æKY HDelete æFp Files.p æT FUNCTION æD FUNCTION HDelete(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255): OSErr; æDT myVariable := HDelete(vRefNum,dirID,fileName); æRI HDelete function IV-147 æKY HGetFInfo æFp Files.p æT FUNCTION æD FUNCTION HGetFInfo(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255; VAR fndrInfo: FInfo): OSErr; æDT myVariable := HGetFInfo(vRefNum,dirID,fileName,fndrInfo); æRI HGetFileInfo function IV-149 æKY HGetVol æFp Files.p æT FUNCTION æD FUNCTION HGetVol(volName: StringPtr;VAR vRefNum: INTEGER;VAR dirID: LONGINT): OSErr; æDT myVariable := HGetVol(volName,vRefNum,dirID); æRI HGetVol function IV-132 æKY HOpen æFp Files.p æT FUNCTION æD FUNCTION HOpen(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255;permission: SignedByte; VAR refNum: INTEGER): OSErr; æDT myVariable := HOpen(vRefNum,dirID,fileName,permission,refNum); æRI HOpen function IV-136 æKY HOpenFile æFp Files.p æT FUNCTION æD FUNCTION HOpenFile(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255; permission: SignedByte;VAR refNum: INTEGER): OSErr; æDT myVariable := HOpenFile(vRefNum,dirID,fileName,permission,refNum); æKY HOpenRF æFp Files.p æT FUNCTION æD FUNCTION HOpenRF(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255;permission: SignedByte; VAR refNum: INTEGER): OSErr; æDT myVariable := HOpenRF(vRefNum,dirID,fileName,permission,refNum); æRI HOpenRF function IV-137 æKY HRename æFp Files.p æT FUNCTION æD FUNCTION HRename(vRefNum: INTEGER;dirID: LONGINT;oldName: Str255;newName: Str255): OSErr; æDT myVariable := HRename(vRefNum,dirID,oldName,newName); æRI HRename function IV-154 æKY HRstFLock æFp Files.p æT FUNCTION æD FUNCTION HRstFLock(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255): OSErr; æDT myVariable := HRstFLock(vRefNum,dirID,fileName); æRI HRstFLock function IV-152 æKY HSetFInfo æFp Files.p æT FUNCTION æD FUNCTION HSetFInfo(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255; fndrInfo: FInfo): OSErr; æDT myVariable := HSetFInfo(vRefNum,dirID,fileName,fndrInfo); æRI HSetFileInfo function IV-150 æKY HSetFLock æFp Files.p æT FUNCTION æD FUNCTION HSetFLock(vRefNum: INTEGER;dirID: LONGINT;fileName: Str255): OSErr; æDT myVariable := HSetFLock(vRefNum,dirID,fileName); æRI HSetFLock function IV-151 æKY HSetVol æFp Files.p æT FUNCTION æD FUNCTION HSetVol(volName: StringPtr;vRefNum: INTEGER;dirID: LONGINT): OSErr; æDT myVariable := HSetVol(volName,vRefNum,dirID); æRI HSetVol function IV-133 æKY ioDirFlg æFp Files.p æC ioDirFlg = 3; æKY ioDirMask æFp Files.p æC ioDirMask = $10; æKY NumVersion æFp Files.p æT PACKED RECORD æC NumVersion = PACKED RECORD CASE INTEGER OF 0: (majorRev: SignedByte; {1st part of version number in BCD} minorRev: 0..9; {2nd part is 1 nibble in BCD} bugFixRev: 0..9; {3rd part is 1 nibble in BCD} stage: SignedByte; {stage code: dev, alpha, beta, final} nonRelRev: SignedByte); {revision level of non-released version} 1: (version: LONGINT); {to use all 4 fields at one time} END; æKY OpenRF æFp Files.p æT FUNCTION æTN $A00A æD FUNCTION OpenRF(fileName: Str255;vRefNum: INTEGER;VAR refNum: INTEGER): OSErr; æDT myVariable := OpenRF(fileName,vRefNum,refNum); æRT 74 æRI OpenRF function N74-1 high-level II-91, IV-109 low-level II-109, IV-137 æC [Not in ROM] OpenRF is similar to FSOpen; the only difference is that OpenRF opens the resource fork of the specified file rather than the data fork. A path reference number is returned in refNum. The access path’s read/write permission is set to whatever the file’s open permission allows. Note: Normally you should access a file’s resource fork through the routines of the Resource Manager rather than the File Manager. OpenRF doesn’t read the resource map into memory; it’s really only useful for block-level operations such as copying files. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing tmfoErr Too many files open æKY OpenWD æFp Files.p æT FUNCTION æTN $A260 æD FUNCTION OpenWD(vRefNum: INTEGER;dirID: LONGINT;procID: LONGINT;VAR wdRefNum: INTEGER): OSErr; æDT myVariable := OpenWD(vRefNum,dirID,procID,wdRefNum); æRT 218 æRI OpenWD function IV-158 æKY PBAllocate æFp Files.p æT FUNCTION æTN $A010 æD FUNCTION PBAllocate(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBAllocate(paramBlock,async); æRI PBAllocate function II-113, IV-143 æC Trap macro _Allocate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocate adds ioReqCount bytes to the open file whose access path is specified by ioRefNum, and sets the physical end-of-file to one byte beyond the last block allocated. The number of bytes actually allocated is rounded up to the nearest multiple of the allocation block size, and returned in ioActCount. If there isn’t enough empty space on the volume to satisfy the allocation request, PBAllocate allocates the rest of the space on the volume and returns dskFulErr as its function result. Note: Even if the total number of requested bytes is unavailable, PBAllocate will allocate whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call PBAllocContig instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBAllocContig æFp Files.p æT FUNCTION æD FUNCTION PBAllocContig(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBAllocContig(paramBlock,async); æRI PBAllocContig function IV-143 æC Trap macro _AllocContig Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word <-- 40 ioActCount long word PBAllocContig is identical to PBAllocate except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, PBAllocContig will do nothing and will return dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled as a contiguous piece, call PBAllocate instead. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBCatMove æFp Files.p æT FUNCTION æD FUNCTION PBCatMove(paramBlock: CMovePBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBCatMove(paramBlock,async); æRI PBCatMove function IV-157 æC •••Refer to Technical Note #226:••• Trap macro _CatMove Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 28 ioNewName pointer --> 36 ioNewDirID long word --> 48 ioDirID long word PBCatMove moves files or directories from one directory to another. The name of the file or directory to be moved is pointed to by ioNamePtr; ioVRefNum contains either the volume reference number or working directory reference number. A directory ID can be specified in ioDirID. The name and directory ID of the directory to which the file or directory is to be moved are specified by ioNewName and ioNewDirID. PBCatMove is strictly a file catalog operation; it does not actually change the location of the file or directory on the disk. PBCatMove cannot move a file or directory to another volume (that is, ioVRefNum is used in specifying both the source and the destination). It also cannot be used to rename files or directories; for that, use PBHRename. Result codes noErr No error badMovErr Attempt to move into offspring bdNamErr Bad file name or attempt to move into a file dupFNErr Duplicate file name and version fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBClose æFp Files.p æT FUNCTION æTN $A001 æD FUNCTION PBClose(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBClose(paramBlock,async); æRI PBClose function IV-144 Device Manager II-184 File Manager II-114 æC Trap macro _Close Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBClose writes the contents of the access path buffer specified by ioRefNum to the volume and removes the access path. Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBCloseWD æFp Files.p æT FUNCTION æD FUNCTION PBCloseWD(paramBlock: WDPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBCloseWD(paramBlock,async); æRI PBCloseWD function IV-158 æC Trap macro _CloseWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 22 ioVRefNum word PBCloseWD releases the working directory whose working directory reference number is specified in ioVRefNum. Note: If a volume reference number is specified in ioVRefNum, PBCloseWD does nothing. Result codes noErr No error nsvErr No such volume æKY PBCreate æFp Files.p æT FUNCTION æTN $A008 æD FUNCTION PBCreate(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBCreate(paramBlock,async); æRI PBCreate function II-107, IV-145 æC Trap macro _Create Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBCreate creates a new file (both forks) having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. The new file is unlocked and empty. The date and time of its creation and last modification are set to the current date and time. If the file created isn’t temporary (that is, if it will exist after the application terminates), the application should call PBSetFInfo (after PBCreate) to fill in the information needed by the Finder. Assembly-language note: If a desk accessory creates a file, it should always create it in the directory containing the system folder. The working directory reference number for this directory is stored in the global variable BootDrive; you can pass it in ioVRefNum. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDelete æFp Files.p æT FUNCTION æTN $A009 æD FUNCTION PBDelete(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBDelete(paramBlock,async); æRI PBDelete function II-119, IV-147 æC Trap macro _Delete Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBDelete removes the closed file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) from the volume pointed to by ioVRefNum. PBHDelete can be used to delete an empty directory as well. Note: This function will delete both forks of the file. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fBsyErr File busy, directory not empty, or working directory control block open fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBDirCreate æFp Files.p æT FUNCTION æD FUNCTION PBDirCreate(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBDirCreate(paramBlock,async); æRI PBDirCreate function IV-146 æC Trap macro _DirCreate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-> 48 ioDirID long word PBDirCreate is identical to PBHCreate except that it creates a new directory instead of a file. You can specify the parent of the directory to be created in ioDirID; if it’s 0, the new directory will be placed in the root directory. The directory ID of the new directory is returned in ioDirID. Warning: PBDirCreate operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full dirNFErr Directory not found or incomplete pathname extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBEject æFp Files.p æT FUNCTION æTN $A017 æD FUNCTION PBEject(paramBlock: ParmBlkPtr): OSErr; æDT myVariable := PBEject(paramBlock); æMM æRI PBEject function II-107, IV-135 æC Trap macro _Eject Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBEject flushes the volume specified by ioNamePtr or ioVRefNum, places it off-line, and then ejects the volume. Assembly-language note: You may invoke the macro _Eject asynchronously; the first part of the call is executed synchronously, and the actual ejection is executed asynchronously. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBFlushFile æFp Files.p æT FUNCTION æTN $A045 æD FUNCTION PBFlushFile(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBFlushFile(paramBlock,async); æRI PBFlushFile function II-114, IV-144 æC Trap macro _FlushFile Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word PBFlushFile writes the contents of the access path buffer indicated by ioRefNum to the volume, and updates the file’s entry in the file directory (or in the file catalog, in the case of hierarchical volumes). Warning: Some information stored on the volume won’t be correct until PBFlushVol is called. Result codes noErr No error extFSErr External file system fnfErr File not found fnOpnErr File not open ioErr I/O error nsvErr No such volume rfNumErr Bad reference number æKY PBFlushVol æFp Files.p æT FUNCTION æTN $A013 æD FUNCTION PBFlushVol(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBFlushVol(paramBlock,async); æMM æRI PBFlushVol function II-105, IV-133 æC Trap macro _FlushVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word On the volume specified by ioNamePtr or ioVRefNum, PBFlushVol writes descriptive information about the volume, the contents of the associated volume buffer, and all access path buffers for the volume (if they’ve changed since the last time PBFlushVol was called). Note: The date and time of the last modification to the volume are set when the modification is made, not when the volume is flushed. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBGetCatInfo æFp Files.p æT FUNCTION æD FUNCTION PBGetCatInfo(paramBlock: CInfoPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetCatInfo(paramBlock,async); æRT 68,69 æRI PBGetCatInfo function IV-155, V-391, N68-1, N69 æC •••Rrefer to Technical Note #69:••• Trap macro _GetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word <-- 24 ioFRefNum word <-- 24 ioFRefNum word --> 28 ioFDirIndex word --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 30 ioFlAttrib byte <-- 31 ioACUser byte access rights for directory only <-- 32 ioFlFndrInfo 16 bytes <-- 32 ioDrUsrWds 16 bytes <-> 48 ioDirID long word <-> 48 ioDrDirID long word <-- 52 ioFlStBlk word <-- 52 ioDrNmFls word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 72 ioDrCrDat long word <-- 76 ioFlMdDat long word <-- 76 ioDrMdDat long word <-- 80 ioFlBkDat long word <-- 80 ioDrBkDat long word <-- 84 ioFlXFndrInfo 16 bytes <-- 84 ioDrFndrInfo 16 bytes <-- 100 ioFlParID long word <-- 100 ioDrParID long word <-- 104 ioFlClpSiz long word PBGetCatInfo gets information about the files and directories in a file catalog. To determine whether the information is for a file or a directory, test bit 4 of ioFlAttrib, as described in the section “CInfoPBRec”. The information that’s returned for files is shown in the left column, and the corresponding information for directories is shown in the right column. If ioFDirIndex is positive, the File Manager returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioVRefNum (this will be the root directory if a volume reference number is provided). If ioFDirIndex is 0, the File Manager returns information about the file or directory specified by ioNamePtr, in the directory specified by ioVRefNum (again, this will be the root directory if a volume reference number is provided). If ioFDirIndex is negative, the File Manager ignores ioNamePtr and returns information about the directory specified by ioDirID. With files, PBGetCatInfo is similar to PBHGetFileInfo but returns some additional information. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). For server volume directories, in addition to the normal return parameters the ioACUser field returns the user’s access rights in the following format: Bit 7 if set, user is not the owner of the directory. if clear, user is the owner of the directory. 6–3 Reserved; this is returned set to zero. 2 If set, user does not have Make Changes privileges to the directory. If clear, user has Make Changes privileges to the directory. 1 If set, user does not have See Files privileges to the directory. If clear, user has See Files privileges to the directory. 0 If set, user does not have See Folders privileges to the directory. If clear, user has See Folders privileges to the directory. For example, if ioACUser returns zero for a given server volume directory, you know that the user is the owner of the directory and has complete privileges to it. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBGetEOF æFp Files.p æT FUNCTION æTN $A011 æD FUNCTION PBGetEOF(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetEOF(paramBlock,async); æRI PBGetEOF function II-112, IV-142 æC Trap macro _GetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 28 ioMisc long word PBGetEOF returns, in ioMisc, the logical end-of-file of the open file whose access path is specified by ioRefNum. Result codes noErr No error extFSErr External file system fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number æKY PBGetFCBInfo æFp Files.p æT FUNCTION æD FUNCTION PBGetFCBInfo(paramBlock: FCBPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetFCBInfo(paramBlock,async); æRT 87 æRI PBGetFCBInfo function IV-179, N87-1 æC Trap macro _GetFCBInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word <-> 24 ioRefNum word --> 28 ioFCBIndx long word <-- 32 ioFCBFlNm long word <-- 36 ioFCBFlags word <-- 38 ioFCBStBlk word <-- 40 ioFCBEOF long word <-- 44 ioFCBPLen long word <-- 48 ioFCBCrPs long word <-- 52 ioFCBVRefNum word <-- 54 ioFCBClpSiz long word <-- 58 ioFCBParID long word PBGetFCBInfo returns information about the specified open file. If ioFCBIndx is positive, the File Manager returns information about the file whose file number is ioFCBIndx on the volume specified by ioVRefNum (which may contain a drive number, volume reference number, or working directory reference number). If ioVRefNum is 0, all open files are indexed; otherwise, only open files on the specified volume are indexed. If ioFCBIndx is 0, the File Manager returns information about the file whose access path is specified by ioRefNum. Assembly-language note: The global variable FCBSPtr points to the length word of the file-control-block buffer. Each file control block contains 94 bytes of information about an access path; Figure 28 shows its structure (using the assembly-language offsets). •••Refer to Figure 28:••• Figure 28–A File Control Block 64K ROM note: The structure of a file control block in the 64K ROM version of the File Manager is a subset of the above structure. The old file control block contained only the fields up to and including fcbFlPos. FCBMdRByt (which corresponds to ioFCBFlags in the parameter block for PBGetFCBInfo) contains flags that describe the status of the file, as follows: Bit Meaning 0 Set if data can be written to the file 1 Set if the entry describes a resource fork 7 Set if the file has been changed since it was last flushed Warning: The size and structure of a file control block may be different in future versions of Macintosh system software. æKY PBGetFInfo æFp Files.p æT FUNCTION æD FUNCTION PBGetFInfo(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetFInfo(paramBlock,async); æRT 24 æRI PBGetFInfo function II-115, IV-148, N24-1, N68-1 æC Trap macro _GetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioFRefNum word --> 26 ioFVersNum byte --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 31 ioFlVersNum byte <-- 32 ioFlFndrInfo 16 bytes <-- 48 ioFlNum long word <-- 52 ioFlStBlk word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 76 ioFlMdDat long word PBGetFInfo returns information about the specified file. If ioFDirIndex is positive, the File Manager returns information about the file whose directory index is ioFDirIndex on the volume specified by ioVRefNum. (See the section “Data Organization on Volumes” if you’re interested in using this method.) Note: If a working directory reference number is specified in ioVRefNum, the File Manager returns information about the file whose directory index is ioFDirIndex in the specified directory. If ioFDirIndex is negative or 0, the File Manager returns information about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. If the file is open, the reference number of the first access path found is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless ioNamePtr is NIL). Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBGetFPos æFp Files.p æT FUNCTION æTN $A018 æD FUNCTION PBGetFPos(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetFPos(paramBlock,async); æRI PBGetFPos function II-111, IV-141 æC Trap macro _GetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word <-- 36 ioReqCount long word <-- 40 ioActCount long word <-- 44 ioPosMode word <-- 46 ioPosOffset long word PBGetFPos returns, in ioPosOffset, the mark of the open file whose access path is specified by ioRefNum. It sets ioReqCount, ioActCount, and ioPosMode to 0. Result codes noErr No error extFSErr External file system fnOpnErr File not open gfpErr Error during GetFPos ioErr I/O error rfNumErr Bad reference number æKY PBGetVInfo æFp Files.p æT FUNCTION æTN $A007 æD FUNCTION PBGetVInfo(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetVInfo(paramBlock,async); æRT 24, 44, 157 æRI PBGetVInfo function II-104, IV-129, N24-1, N44-2, N157 æC Trap macro _GetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsBkUp long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVDirSt word <-- 44 ioVBlLn word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word PBGetVInfo returns information about the specified volume. If ioVolIndex is positive, the File Manager attempts to use it to find the volume; for instance, if ioVolIndex is 2, the File Manager will attempt to access the second mounted volume. If ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way (described in the section “Specifying Volumes, Directories, and Files”) to determine which volume. If ioVolIndex is 0, the File Manager attempts to access the volume by using ioVRefNum only. The volume reference number is returned in ioVRefNum, and a pointer to the volume name is returned in ioNamePtr (unless ioNamePtr is NIL). If a working directory reference number is passed in ioVRefNum (or if the default directory is a subdirectory), the number of files and directories in the specified directory (the directory’s valence) will be returned in ioVNmFls. Also, the volume reference number won’t be returned; ioVRefNum will still contain the working directory reference number. Warning: IOVNmAlBlks and ioVFrBlks, which are actually unsigned integers, are clipped to 31744 ($7C00) regardless of the size of the volume. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBGetVol æFp Files.p æT FUNCTION æTN $A014 æD FUNCTION PBGetVol(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetVol(paramBlock,async); æRI PBGetVol function II-104, IV-131 æC Trap macro _GetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word PBGetVol returns a pointer to the name of the default volume in ioNamePtr (unless ioNamePtr is NIL) and its volume reference number in ioVRefNum. If a default directory was set with a previous PBSetVol call, a pointer to its name will be returned in ioNamePtr and its working directory reference number in ioVRefNum. Result codes noErr No error nsvErr No default volume æKY PBGetWDInfo æFp Files.p æT FUNCTION æD FUNCTION PBGetWDInfo(paramBlock: WDPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBGetWDInfo(paramBlock,async); æRT 77, 190 æRI PBGetWDInfo function IV-159, N77-5 æC Trap macro _GetWDInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 26 ioWDIndex word <-> 28 ioWDProcID long word <-> 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBGetWDInfo returns information about the specified working directory. The working directory can be specified either by its working directory reference number in ioVRefNum (in which case ioWDIndex should be 0), or by its index number in ioWDIndex. In the latter case, if ioVRefNum is nonzero, it’s interpreted as a volume specification (volume reference number or drive number), and only working directories on that volume are indexed. IOWDVRefNum always returns the volume reference number. IOVRefNum returns a working directory reference number when a working directory reference number is passed in that field; otherwise, it returns a volume reference number. The volume name is returned in ioNamePtr. If IOWDProcID is nonzero, only working directories with that identifier are indexed; otherwise all working directories are indexed. Result codes noErr No error nsvErr No such volume æKY PBHCopyFile æFp Files.p æT FUNCTION æD FUNCTION PBHCopyFile(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHCopyFile(paramBlock,async); æRI PBHCopyFile function V-396 æC Trap macro _CopyFile Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long ptr to source pathname --> 22 ioVRefNum word source vol identifier --> 24 ioDstVRefNum word destination vol identifier --> 28 ioNewName long ptr to destination pathname --> 32 ioCopyName long ptr to optional name (may be NIL) --> 36 ioNewDirID long destination directory ID --> 48 ioDirID long source directory ID PBHCopyFile duplicates a file on the volume and optionally renames it. It is an optional call for AppleShare file servers. You should examine the returned flag information in the PBHGetVolParms call to see if this volume supports CopyFile. For AppleShare file servers, the source and destination pathnames must indicate the same file server; however, it may point to a different volume for that file server. A useful way to tell if two file server volumes are on the same file server is to make the GetVolParms call and compare the server addresses returned. The server will open source files with read/deny write enabled and destination files with write/deny read and write enabled. IOVRefNum contains a source volume identifier. The source pathname is determined by the ioFileName/ioDirID pair. IODstVRefNum contains a destination volume identifier. AppleShare 1.0 required that it be an actual volume reference number; however, on future versions it can be a WDRefNum. The destination pathname is determined by the ioNewName/ioNewDirID pair. IOCopyName may contain an optional string used in renaming the file. If it is non-NIL then the file copy will be renamed to the specified name in ioCopyName. A fnfErr is returned if the source pathname does not point to an existing file or the destination pathname does not point to an existing directory. An AccessDenied error is returned if the user does not have the right to read the source or write to the destination. A dupFnErr is returned if the destination already exists. A DenyConflict error is returned if either the source or destination file could not be opened under the access modes described above. æKY PBHCreate æFp Files.p æT FUNCTION æD FUNCTION PBHCreate(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHCreate(paramBlock,async); æRI PBHCreate function IV-146 æC Trap macro _HCreate Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioDirID long word PBHCreate is identical to PBCreate except that it accepts a directory ID in ioDirID. Note: To create a directory instead of a file, call PBDirCreate. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version dirFulErr File directory full dirNFErr Directory not found or incomplete pathname extFSErr External file system ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBHDelete æFp Files.p æT FUNCTION æD FUNCTION PBHDelete(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHDelete(paramBlock,async); æRI PBHDelete function IV-147 æC Trap macro _HDelete Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioDirID long word PBHDelete is identical to PBDelete except that it accepts a directory ID in ioDirID. PBHDelete can be used to delete an empty directory as well. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fBsyErr File busy, directory not empty, or working directory control block open fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBHGetDirAccess æFp Files.p æT FUNCTION æD FUNCTION PBHGetDirAccess(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHGetDirAccess(paramBlock,async); æRI PBHGetDirAccess function V-394 æC Trap macro _GetDirAccess Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long directory name --> 22 ioVRefNum word volume refNum <-- 36 ioACOwnerID long owner ID <-- 40 ioACGroupID long group ID <-- 44 ioACAccess long access rights --> 48 ioDirID long directory ID PBHGetDirAccess returns access control information for the folder pointed to by the ioDirID/ioFIleName pair. ioACOwnerID will return the ID for the folder’s owner. ioACGroupID will return the ID for the folder’s primary group. The access rights are returned in ioACAccess. A fnfErr is returned if the pathname does not point to a valid directory. An AccessDenied error is returned if the user does not have the correct access rights to examine this directory. æKY PBHGetFInfo æFp Files.p æT FUNCTION æD FUNCTION PBHGetFInfo(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHGetFInfo(paramBlock,async); æRI PBHGetFInfo function IV-149 æC Trap macro _HGetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioFRefNum word --> 28 ioFDirIndex word <-- 30 ioFlAttrib byte <-- 32 ioFlFndrInfo 16 bytes <-> 48 ioDirID long word <-- 52 ioFlStBlk word <-- 54 ioFlLgLen long word <-- 58 ioFlPyLen long word <-- 62 ioFlRStBlk word <-- 64 ioFlRLgLen long word <-- 68 ioFlRPyLen long word <-- 72 ioFlCrDat long word <-- 76 ioFlMdDat long word PBHGetFInfo is identical to PBGetFInfo except that it accepts a directory ID in ioDirID. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBHGetLogInInfo æFp Files.p æT FUNCTION æD FUNCTION PBHGetLogInInfo(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHGetLogInInfo(paramBlock,async); æRI PBHGetLogInInfo function V-393 æC Trap macro _GetLogInInfo Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 22 ioVRefNum word volume refNum <-- 26 ioObjType word log in method <-- 28 ioObjNamePtr long ptr to log in name buffer PBHGetLogInInfo returns the method used for log-in and the user name specified at log-in time for the volume. The log-in user name is returned as a Pascal string in ioObjNamePtr. The maximum size of the user name is 31 characters. The log-in method type is returned in ioObjType. æKY PBHGetVInfo æFp Files.p æT FUNCTION æD FUNCTION PBHGetVInfo(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHGetVInfo(paramBlock,async); æRT 24, 66, 67, 77, 106, 157 æRI PBHGetVInfo function IV-130, N66-1, N67-1, N77-5 æC Trap macro _HGetVInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioVolIndex word <-- 30 ioVCrDate long word <-- 34 ioVLsMod long word <-- 38 ioVAtrb word <-- 40 ioVNmFls word <-- 42 ioVBitMap word <-- 44 ioVAllocPtr word <-- 46 ioVNmAlBlks word <-- 48 ioVAlBlkSiz long word <-- 52 ioVClpSiz long word <-- 56 ioAlBlSt word <-- 58 ioVNxtFNum long word <-- 62 ioVFrBlk word <-- 64 ioVSigWord word <-- 66 ioVDrvInfo word <-- 68 ioVDRefNum word <-- 70 ioVFSID word <-- 72 ioVBkUp long word <-- 76 ioVSeqNum word <-- 78 ioVWrCnt long word <-- 82 ioVFilCnt long word <-- 86 ioVDirCnt long word <-- 90 ioVFndrInfo 32 bytes PBHGetVInfo is similar in function to PBGetVInfo but returns a larger parameter block. In addition, PBHGetVInfo always returns the volume reference number in ioVRefNum (regardless of what was passed in). Also, ioVNmAlBlks and ioVFrBlks are not clipped as they are by PBGetVInfo. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBHGetVol æFp Files.p æT FUNCTION æD FUNCTION PBHGetVol(paramBlock: WDPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHGetVol(paramBlock,async); æRI PBHGetVol function IV-132 æC Trap macro _HGetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word <-- 18 ioNamePtr pointer <-- 22 ioVRefNum word <-- 28 ioWDProcID long word <-- 32 ioWDVRefNum word <-- 48 ioWDDirID long word PBHGetVol returns the default volume and directory last set by either a PBSetVol or a PBHSetVol call. The reference number of the default volume is returned in ioVRefNum. Warning: IOVRefNum will return a working directory reference number (instead of the volume reference number) if, in the last call to PBSetVol or PBHSetVol, a working directory reference number was passed in this field. The volume reference number of the volume on which the default directory exists is returned in ioWDVRefNum. The directory ID of the default directory is returned in ioWDDirID. Result codes noErr No error nsvErr No default volume æKY PBHGetVolParms æFp Files.p æT FUNCTION æD FUNCTION PBHGetVolParms(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHGetVolParms(paramBlock,async); æRI PBHGetVolParms function V-392 æC Trap macro _GetVolParms Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long volume name specifier --> 22 ioVRefNum word volume refNum <-- 32 ioBuffer long ptr to vol parms data --> 36 ioReqCount long size of buffer area <-- 40 ioActCount long length of vol parms data The PBHGetVolParms call is used to return volume level information. ioVRefNum or ioFileName contain the volume identifier information. ioReqCount and ioBuffer contain the size and location of the buffer in which to place the volume parameters. The actual size of the information is returned in ioActCount. The format of the buffer is described below. Version 01 of the buffer is shown below along with offsets into the buffer and their equates: offset 0 vMVersion word version number (currently 01) 2 vMAttrib long attributes (detailed below) 6 vMLocalHand long handle used to keep information necessary for shared volumes 10 vMServerAdr long AppleTalk server address (zero if not supported) On creation of the VCB (right after mounting), vMLocalHand will be a handle to a 2 byte block of memory. The Finder uses this for its local window list storage, allocating and deallocating memory as needed. It is disposed of when the volume is unmounted. For AppleTalk server volumes, vMServerAdr contains the AppleTalk internet address of the server. This can be used to tell which volumes are for which server. vMAttrib contains attributes information (32 flag bits) about the volume. These bits and their equates are defined as follows: bit 31 bLimitFCBs If set, Finder limits the number of FCBs used during copies to 8 (instead of 16). 30 bLocalWList If set, Finder uses the returned shared volume handle for its local window list. 29 bNoMiniFndr If set, Mini Finder menu item is disabled. 28 bNoVNEdit If set, volume name cannot be edited. 27 bNoLclSync If set, volume’s modification date is not set by any Finder action. 26 bTrshOffLine If set, anytime volume goes offline, it is zoomed to the Trash and unmounted. 25 bNoSwitchTo If set, Finder will not switch launch to any application on the volume. 24–21 Reserved—server volumes should return these bits set, all other disks should return these bits cleared. 20 bNoDeskItems If set, no items may be placed on the Finder desktop. 19 bNoBootBlks If set, no boot blocks on this volume—not a startup volume. SetStartup menu item will be disabled; bootblocks will not be copied during copy operations. 18 bAccessCntl If set, volume supports AppleTalk AFP access control interfaces. The calls GetLoginInfo, GetDirAccess, SetDirAccess, MapID, and MapName are supported. Special folder icons are used. Access Privileges menu item is enabled for disk and folder items. The privileges field of GetCatInfo calls are assumed to be valid. 17 bNoSysDir If set, volume doesn’t support a system directory; no switch launch to this volume. 16 bExtFSVol If set, this volume is an external file system volume. Disk init package will not be called. Erase Disk menu item is disabled. 15 bHasOpenDeny If set, supports _OpenDeny and _OpenRFDeny calls. For copy operations, source files are opened with enable read/deny write and destination files are opened enable write/deny read and write. 14 bHasCopyFile If set, _CopyFile call supported. _CopyFile is used in copy and duplicate operations if both source and destination volumes have same server address. 13 bHasMoveRename If set, _MoveRename call supported. 12 bHasNewDesk If set, all of the new desktop calls are supported (for example, OpenDB, AddIcon, AddComment). 11–0 Reserved—these bits should be returned cleared. æKY PBHMapID æFp Files.p æT FUNCTION æD FUNCTION PBHMapID(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHMapID(paramBlock,async); æRI PBHMapID function V-395 æC Trap macro _MapID Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long pathname identifier --> 22 ioVRefNum word volume refNum --> 26 ioObjType word function code <-- 28 ioObjNamePtr long ptr to retrnd creator/group name --> 32 ioObjID long creator/group ID PBHMapID returns the name of a user or group given its unique ID. IOObjID contains the ID to be mapped. The value zero for ioObjID is special cased and will always return a NIL name. AppleShare uses this to signify <Any User>. IOObjType is the mapping function code; it’s 1 if you’re mapping an owner ID to owner name or 2 if you’re mapping a group ID to a group name. The name is returned as a Pascal string in ioObjNamePtr. The maximum size of the name is 31 characters. A fnfErr is returned if an unrecognizable owner or group ID is passed. æKY PBHMapName æFp Files.p æT FUNCTION æD FUNCTION PBHMapName(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHMapName(paramBlock,async); æRI PBHMapName function V-395 æC Trap macro _MapName Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long volume identifier (may be NIL) --> 22 ioVRefNum word volume refNum --> 28 ioObjNamePtr long owner or group name --> 26 ioObjType word function code <-- 32 ioObjID long creator/group ID PBHMapName returns the unique user ID or group ID given its name. The name is passed as a string in ioObjNamePtr. If a NIL name is passed, the ID returned will always be zero. The maximum size of the name is 31 characters. IOObjType is the mapping function code; it’s 3 if you’re mapping an owner name to owner ID or 4 if you’re mapping a group name to a group ID. IOObjID will contain the mapped ID. A fnfErr is returned if an unrecognizable owner or group name is passed. æKY PBHMoveRename æFp Files.p æT FUNCTION æD FUNCTION PBHMoveRename(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHMoveRename(paramBlock,async); æRI PBHMoveRename function V-397 æC Trap macro _MoveRename Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long ptr to source pathname --> 22 ioVRefNum word source vol identifier --> 28 ioNewName long ptr to destination pathname --> 32 ioBuffer long ptr to optional name (may be NIL) --> 36 ioNewDirID long destination directory ID --> 48 ioDirID long source directory ID PBHMoveRename allows you to move (not copy) an item and optionally to rename it. The source and destination pathnames must point to the same file server volume. IOVRefNum contains a source volume identifier. The source pathname is specified by the ioFileName/ioDirID pair. The destination pathname is specified by the ioNewName/ioNewDirID pair. IOBuffer may contain an optional string used in renaming the item. If it is non-NIL then the moved object will be renamed to the specified name in ioBuffer. A fnfErr is returned if the source pathname does not point to an existing object. An AccessDenied error is returned if the user does not have the right to move the object. A dupFnErr is returned if the destination already exists. A badMovErr is returned if an attempt is made to move a directory into one of its descendent directories. æKY PBHOpen æFp Files.p æT FUNCTION æD FUNCTION PBHOpen(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHOpen(paramBlock,async); æRT 204 æRI PBHOpen function IV-136 æC Trap macro _HOpen Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 27 ioPermssn byte --> 28 ioMisc pointer --> 48 ioDirID long word PBHOpen is identical to PBOpen except that it accepts a directory ID in ioDirID. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBHOpenDeny æFp Files.p æT FUNCTION æD FUNCTION PBHOpenDeny(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHOpenDeny(paramBlock,async); æRI PBHOpenDeny function V-398 æC Trap macro _OpenDeny Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long ptr to pathname --> 22 ioVRefNum word vol identifier <-- 24 ioRefNum word file refNum --> 26 ioDenyModes word access rights data --> 48 ioDirID long directory ID PBHOpenDeny opens a file’s data fork under specific access rights. It creates an access path to the file having the name pointed to by ioFileName/ioDirID. The path reference number is returned in ioRefNum. IODenyModes contains a word of access rights information. The format for these access rights is: bits 15–6 Reserved—should be cleared. 5 If set, other writers are denied access. 4 If set, other readers are denied access. 3–2 Reserved—should be cleared. 1 If set, write permission requested. 0 If set, read permission requested. A fnfErr is returned if the input specification does not point to an existing file. A permErr is returned if the file is already open and you cannot open it under the deny modes that you have specified. An opWrErr is returned if you have asked for write permission and the file is already opened by you for write. The already opened path reference number is returned in ioRefNum. An AccessDenied error is returned if you do not have the right to access the file. æKY PBHOpenFile æFp Files.p æT FUNCTION æD FUNCTION PBHOpenFile(paramBlock: HParmBlkPtr): OSErr; æDT myVariable := PBHOpenFile(paramBlock); æKY PBHOpenRF æFp Files.p æT FUNCTION æD FUNCTION PBHOpenRF(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHOpenRF(paramBlock,async); æRI PBHOpenRF function IV-137 æC Trap macro _HOpenRF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 27 ioPermssn byte --> 28 ioMisc pointer --> 48 ioDirID long word PBHOpenRF is identical to PBOpenRF except that it accepts a directory ID in ioDirID. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBHOpenRFDeny æFp Files.p æT FUNCTION æD FUNCTION PBHOpenRFDeny(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHOpenRFDeny(paramBlock,async); æRI PBHOpenRFDeny function V-398 æC Trap macro _OpenRFDeny Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long ptr to pathname --> 22 ioVRefNum word vol identifier <-- 24 ioRefNum word file refNum --> 26 ioDenyModes word access rights data --> 48 ioDirID long directory ID PBHOpenRFDeny opens a file’s resource fork under specific access rights. It creates an access path to the file having the name pointed to by ioFileName/ioDirID. The path reference number is returned in ioRefNum. The format of the access rights data contained in ioDenyModes is described under the OpenDeny call. A fnfErr is returned if the input specification does not point to an existing file. A permErr is returned if the file is already open and you cannot open it under the deny modes that you have specified. An opWrErr is returned if you have asked for write permission and the file is already opened by you for write. The already-opened path reference number is returned in ioRefNum. An AccessDenied error is returned if you do not have the right to access the file. æKY PBHRename æFp Files.p æT FUNCTION æD FUNCTION PBHRename(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHRename(paramBlock,async); æRI PBHRename function IV-154 æC Trap macro _HRename Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 28 ioMisc pointer --> 48 ioDirID long word PBHRename is identical to PBRename except that it accepts a directory ID in ioDirID and can be used to rename directories as well as files and volumes. Given a pointer to the name of a file or directory in ioNamePtr, PBHRename changes it to the name pointed to by ioMisc. Given a pointer to a volume name in ioNamePtr or a volume reference number in ioVRefNum, it changes the name of the volume to the name pointed to by ioMisc. Warning: PBHRename cannot be used to change the directory a file is in. Result codes noErr No error bdNamErr Bad file name dirFulErr File directory full dirNFErr Directory not found or incomplete pathname dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found fsRnErr Problem during rename ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBHRstFLock æFp Files.p æT FUNCTION æD FUNCTION PBHRstFLock(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHRstFLock(paramBlock,async); æRI PBHRstFLock function IV-152 æC Trap macro _HRstFLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioDirID long word PBHRstFLock is identical to PBRstFLock except that it accepts a directory ID in ioDirID. Result codes noErr No error dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBHSetDirAccess æFp Files.p æT FUNCTION æD FUNCTION PBHSetDirAccess(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHSetDirAccess(paramBlock,async); æRI PBHSetDirAccess function V-394 æC Trap macro _SetDirAccess Parameter block --> 12 ioCompletion long optional completion routine ptr <-- 16 ioResult word error result code --> 18 ioFileName long pathname identifier --> 22 ioVRefNum word volume refNum --> 36 ioACOwnerID long owner ID --> 40 ioACGroupID long group ID --> 44 ioACAccess long access rights --> 48 ioDirID long directory ID PBHSetDirAccess allows you to change the access rights to a folder pointed to by the ioFileName/ioDirID pair. IOACOwnerID contains the new owner ID. IOACGroupID contains the group ID. IOACAccess contains the folder’s access rights. You cannot set the owner bit or the user’s rights of the directory. To change the owner or group, you should set the ioACOwnerID or ioACGroupID field with the appropriate ID of the new owner/group. You must be the owner of the directory to change the owner or group ID. A fnfErr is returned if the pathname does not point to a valid directory. An AccessDenied error is returned if you do not have the correct access rights to modify the parameters for this directory. A paramErr is returned if you try to set the owner bit or user’s rights bits. æKY PBHSetFInfo æFp Files.p æT FUNCTION æD FUNCTION PBHSetFInfo(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHSetFInfo(paramBlock,async); æRI PBHSetFInfo function IV-150 æC Trap macro _HSetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 32 ioFlFndrInfo 16 bytes --> 48 ioDirID long word --> 72 ioFlCrDat long word --> 76 ioFlMdDat long word PBHSetFInfo is identical to PBSetFInfo except that it accepts a directory ID in ioDirID. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBHSetFLock æFp Files.p æT FUNCTION æD FUNCTION PBHSetFLock(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHSetFLock(paramBlock,async); æRI PBHSetFLock function IV-151 æC Trap macro _HSetFLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioDirID long word PBHSetFLock is identical to PBSetFLock except that it accepts a directory ID in ioDirID. Result codes noErr No error dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBHSetVol æFp Files.p æT FUNCTION æD FUNCTION PBHSetVol(paramBlock: WDPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBHSetVol(paramBlock,async); æRT 140 æRI PBHSetVol function IV-133, N140 æC •••Refer to Technical Note #140:••• Trap macro _HSetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 48 ioWDDirID long word PBHSetVol sets both the default volume and the default directory. The default directory to be used can be specified by either a volume reference number or a working directory reference number in ioVRefNum, a directory ID in ioWDDirID, or a pointer to a pathname (possibly NIL) in ioNamePtr. Note: Both the default volume and the default directory are used in calls made with no volume name and a volume reference number of zero. Result codes noErr No error nsvErr No default volume æKY PBLockRange æFp Files.p æT FUNCTION æD FUNCTION PBLockRange(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBLockRange(paramBlock,async); æRT 186 æRI PBLockRange function IV-138 æC •••Refer to Technical Note #186:••• Trap macro _LockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word On a file opened with a shared read/write permission, PBLockRange is used in conjunction with PBRead and PBWrite to lock a certain portion of the file. PBLockRange uses the same parameters as both PBRead and PBWrite; by calling it immediately before PBRead, you can use the information present in the parameter block for the PBRead call. When you’re finished with the data (typically after a call to PBWrite), be sure to call PBUnlockRange to free up that portion of the file for subsequent PBRead calls. Warning: PBLockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBMountVol æFp Files.p æT FUNCTION æTN $A00F æD FUNCTION PBMountVol(paramBlock: ParmBlkPtr): OSErr; æDT myVariable := PBMountVol(paramBlock); æMM æRT 134 æRI PBMountVol function II-103, IV-128 æC »Accessing Volumes To get the volume reference number of a volume, given the path reference number of a file on that volume, both Pascal and assembly-language programmers can call the high-level File Manager function GetVRefNum. Assembly-language programmers may prefer calling the function GetFCBInfo (described below in the section “Data Structures in Memory”). FUNCTION PBMountVol (paramBlock: ParmBlkPtr) : OSErr; Trap macro _MountVol Parameter block <-- 16 ioResult word <-> 22 ioVRefNum word PBMountVol mounts the volume in the drive specified by ioVRefNum, and returns a volume reference number in ioVRefNum. If there are no volumes already mounted, this volume becomes the default volume. PBMountVol is always executed synchronously. Note: When mounting hierarchical volumes, PBMountVol opens two files needed for maintaining file directory and file mapping information. PBMountVol can fail if there are no access paths available for these two files; it will return tmfoErr as its function result. Result codes noErr No error badMDBErr Bad master directory block extFSErr External file system ioErr I/O error memFullErr Not enough room in heap zone noMacDskErr Not a Macintosh disk nsDrvErr No such drive paramErr Bad drive number tmfoErr Too many files open volOnLinErr Volume already on-line æKY PBOffLine æFp Files.p æT FUNCTION æTN $A035 æD FUNCTION PBOffLine(paramBlock: ParmBlkPtr): OSErr; æDT myVariable := PBOffLine(paramBlock); æMM æRI PBOffLine function II-106, IV-134 æC Trap macro _OffLine Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBOffLine places off-line the volume specified by ioNamePtr or ioVRefNum, by calling PBFlushVol to flush the volume and releasing all the memory used for the volume except for the volume control block. PBOffLine is always executed synchronously. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBOpen æFp Files.p æT FUNCTION æTN $A000 æD FUNCTION PBOpen(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBOpen(paramBlock,async); æRI PBOpen function IV-135 Device Manager II-184 File Manager II-108 æC Trap macro _Open Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpen creates an access path to the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum. A path reference number is returned in ioRefNum. IOMisc either points to a portion of memory (522 bytes) to be used as the access path’s buffer, or is NIL if you want the volume buffer to be used instead. Warning: All access paths to a single file that’s opened multiple times should share the same buffer so that they will read and write the same data. IOPermssn specifies the path’s read/write permission. A path can be opened for writing even if it accesses a file on a locked volume, and an error won’t be returned until a PBWrite, PBSetEOF, or PBAllocate call is made. If you attempt to open a locked file for writing, PBOpen will return permErr as its function result. If you request exclusive read/write permission but another access path already has write permission (whether write only, exclusive read/write, or shared read/write), PBOpen will return the reference number of the existing access path in ioRefNum and opWrErr as its function result. Similarly, if you request shared read/write permission but another access path already has exclusive read/write permission, PBOpen will return the reference number of the access path in ioRefNum and opWrErr as its function result. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBOpenFile æFp Files.p æT FUNCTION æD FUNCTION PBOpenFile(paramBlock: ParmBlkPtr): OSErr; æDT myVariable := PBOpenFile(paramBlock); æKY PBOpenRF æFp Files.p æT FUNCTION æTN $A00A æD FUNCTION PBOpenRF(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBOpenRF(paramBlock,async); æMM æRT 74 æRI PBOpenRF function II-109, IV-137 æC Trap macro _OpenRF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word <-- 24 ioRefNum word --> 26 ioVersNum byte --> 27 ioPermssn byte --> 28 ioMisc pointer PBOpenRF is identical to PBOpen, except that it opens the file’s resource fork instead of its data fork. Note: Normally you should access a file’s resource fork through the routines of the Resource Manager rather than the File Manager. PBOpenRF doesn’t read the resource map into memory; it’s really only useful for block-level operations such as copying files. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume opWrErr File already open for writing permErr Attempt to open locked file for writing tmfoErr Too many files open æKY PBOpenWD æFp Files.p æT FUNCTION æD FUNCTION PBOpenWD(paramBlock: WDPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBOpenWD(paramBlock,async); æRT 77, 190 æRI PBOpenWD function IV-158, N77-1 æC Trap macro _OpenWD Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer <-> 22 ioVRefNum word --> 28 ioWDProcID long word --> 48 ioWDDirID long word PBOpenWD takes the directory specified by ioVRefNum, ioWDDirID, and ioWDProcID and makes it a working directory. (You can also specify the directory using a combination of partial pathname and directory ID.) It returns a working directory reference number in ioVRefNum that can be used in subsequent calls. If a given directory has already been made a working directory using the same ioWDProcID, no new working directory will be opened; instead, the existing working directory reference number will be returned. If a given directory was already made a working directory using a different ioWDProcID, a new working directory reference number is returned. Result codes noErr No error tmwdoErr Too many working directories open æKY PBRead æFp Files.p æT FUNCTION æTN $A002 æD FUNCTION PBRead(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBRead(paramBlock,async); æRT 187 æRI PBRead function IV-139 Device Manager II-185 File Manager II-110 æC Trap macro _Read Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBRead attempts to read ioReqCount bytes from the open file whose access path is specified by ioRefNum, and transfer them to the data buffer pointed to by ioBuffer. The position of the mark is specified by ioPosMode and ioPosOffset. If you try to read past the logical end-of-file, PBRead moves the mark to the end-of-file and returns eofErr as its function result. After the read is completed, the mark is returned in ioPosOffset and the number of bytes actually read is returned in ioActCount. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBRename æFp Files.p æT FUNCTION æTN $A00B æD FUNCTION PBRename(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBRename(paramBlock,async); æRI PBRename function II-118, IV-153 æC Trap macro _Rename Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc pointer Given a pointer to a file name in ioNamePtr (and on flat volumes, a version number in ioVersNum), PBRename changes the name of the file to the name pointed to by ioMisc. (If the name pointed to by ioNamePtr contains one or more colons, so must the name pointed to by ioMisc.) Access paths currently in use aren’t affected. Given a pointer to a volume name in ioNamePtr or a volume reference number in ioVRefNum, it changes the name of the volume to the name pointed to by ioMisc. If a volume to be renamed is specified by its volume reference number, ioNamePtr can be NIL. Warning: If a volume to be renamed is specified by its volume name, be sure that it ends with a colon, or Rename will consider it a file name. Result codes noErr No error bdNamErr Bad file name dirFulErr File directory full dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found fsRnErr Problem during rename ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBRstFLock æFp Files.p æT FUNCTION æTN $A042 æD FUNCTION PBRstFLock(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBRstFLock(paramBlock,async); æRI PBRstFLock function II-117, IV-152 æC Trap macro _RstFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBRstFLock unlocks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetCatInfo æFp Files.p æT FUNCTION æD FUNCTION PBSetCatInfo(paramBlock: CInfoPBPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetCatInfo(paramBlock,async); æRI PBSetCatInfo function IV-156 æC Trap macro _SetCatInfo Parameter block Files: Directories: --> 12 ioCompletion pointer --> 12 ioCompletion pointer <-- 16 ioResult word <-- 16 ioResult word <-> 18 ioNamePtr pointer <-> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 22 ioVRefNum word --> 30 ioFlAttrib byte --> 30 ioFlAttrib byte --> 32 ioFlFndrInfo 16 bytes --> 32 ioDrUsrWds 16 bytes --> 48 ioDirID long word --> 48 ioDrDirID long word --> 72 ioFlCrDat long word --> 72 ioDrCrDat long word --> 76 ioFlMdDat long word --> 76 ioDrMdDat long word --> 80 ioFlBkDat long word --> 80 ioDrBkDat long word --> 84 ioFlXFndrInfo 16 bytes --> 84 ioDrFndrInfo 16 bytes --> 104 ioFlClpSiz long word PBSetCatInfo sets information about the files and directories in a catalog. With files, it’s similar to PBHSetFileInfo but lets you set some additional information. The information that can be set for files is shown in the left column, and the corresponding information for directories is shown in the right column. Result codes noErr No error bdNamErr Bad file name dirNFErr Directory not found or incomplete pathname extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume paramErr No default volume æKY PBSetEOF æFp Files.p æT FUNCTION æTN $A012 æD FUNCTION PBSetEOF(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetEOF(paramBlock,async); æRI PBSetEOF function II-112, IV-142 æC Trap macro _SetEOF Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 28 ioMisc long word PBSetEOF sets the logical end-of-file of the open file, whose access path is specified by ioRefNum, to ioMisc. If you attempt to set the logical end-of-file beyond the physical end-of-file, another allocation block is added to the file; if there isn’t enough space on the volume, no change is made, and PBSetEOF returns dskFulErr as its function result. If ioMisc is 0, all space occupied by the file on the volume is released. Result codes noErr No error dskFulErr Disk full extFSErr External file system fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY PBSetFInfo æFp Files.p æT FUNCTION æTN $A00D æD FUNCTION PBSetFInfo(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetFInfo(paramBlock,async); æRI PBSetFInfo function II-116, IV-150 æC Trap macro _SetFileInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte --> 32 ioFlFndrInfo 16 bytes --> 72 ioFlCrDat long word --> 76 ioFlMdDat long word PBSetFInfo sets information (including the date and time of creation and modification, and information needed by the Finder) about the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. You should call PBGetFInfo just before PBSetFInfo, so the current information is present in the parameter block. Result codes noErr No error bdNamErr Bad file name extFSErr External file system fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFLock æFp Files.p æT FUNCTION æTN $A041 æD FUNCTION PBSetFLock(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetFLock(paramBlock,async); æRI PBSetFLock function II-116, IV-151 æC Trap macro _SetFilLock Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioFVersNum byte PBSetFLock locks the file having the name pointed to by ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY PBSetFPos æFp Files.p æT FUNCTION æTN $A044 æD FUNCTION PBSetFPos(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetFPos(paramBlock,async); æRI PBSetFPos function II-111, IV-141 æC Trap macro _SetFPos Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBSetFPos sets the mark of the open file whose access path is specified by ioRefNum to the position specified by ioPosMode and ioPosOffset. The position at which the mark is actually set is returned in ioPosOffset. If you try to set the mark past the logical end-of-file, PBSetFPos moves the mark to the end-of-file and returns eofErr as its function result. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error posErr Attempt to position before start of file rfNumErr Bad reference number æKY PBSetFVers æFp Files.p æT FUNCTION æTN $A043 æD FUNCTION PBSetFVers(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetFVers(paramBlock,async); æRI PBSetFVers function II-117, IV-153 æC Trap macro _SetFilType Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 26 ioVersNum byte --> 28 ioMisc byte PBSetFVers has no effect on hierarchical volumes. On flat volumes, PBSetFVers changes the version number of the file having the name pointed to by ioNamePtr and version number ioVersNum, on the volume specified by ioVRefNum, to the version number stored in the high-order byte of ioMisc. Access paths currently in use aren’t affected. Result codes noErr No error bdNamErr Bad file name dupFNErr Duplicate file name and version extFSErr External file system fLckdErr File locked fnfErr File not found nsvErr No such volume ioErr I/O error paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock wrgVolTypErr Attempt to perform hierarchical operation on a flat volume æKY PBSetVInfo æFp Files.p æT FUNCTION æD FUNCTION PBSetVInfo(paramBlock: HParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetVInfo(paramBlock,async); æRT 204 æRI PBSetVInfo function IV-131 æC •••Refer to Technical Note #204:••• Trap macro _SetVolInfo Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word --> 30 ioVCrDate long word --> 34 ioVLsMod long word --> 38 ioVAtrb word --> 52 ioVClpSiz long word --> 72 ioVBkUp long word --> 76 ioVSeqNum word --> 90 ioVFndrInfo 32 bytes PBSetVInfo lets you modify information about volumes. A pointer to a new name for the volume can be specified in ioNamePtr. The date and time of the volume’s creation and modification can be set with ioVCrDate and ioVLsMod respectively. Only bit 15 of ioVAtrb can be changed; setting it locks the volume. Note: The volume cannot be specified by name; you must use either the volume reference number or the drive number. Warning: PBSetVInfo operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error nsvErr No such volume paramErr No default volume æKY PBSetVol æFp Files.p æT FUNCTION æTN $A015 æD FUNCTION PBSetVol(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBSetVol(paramBlock,async); æRI PBSetVol function II-105, IV-132 æC Trap macro _SetVol Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBSetVol sets the default volume to the mounted volume specified by ioNamePtr or ioVRefNum. On hierarchical volumes, PBSetVol also sets the root directory as the default directory. Result codes noErr No error bdNamErr Bad volume name nsvErr No such volume paramErr No default volume æKY PBUnlockRange æFp Files.p æT FUNCTION æD FUNCTION PBUnlockRange(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBUnlockRange(paramBlock,async); æRT 186 æRI PBUnlockRange function IV-139 æC Trap macro _UnlockRng Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 36 ioReqCount long word --> 44 ioPosMode word --> 46 ioPosOffset long word PBUnlockRange is used in conjunction with PBRead and PBWrite to unlock a certain portion of a file that you locked with PBLockRange. Warning: PBUnlockRange operates only with the hierarchical version of the File Manager; if used on a Macintosh equipped only with the 64K ROM version of the File Manager, it will generate a system error. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount rfNumErr Bad reference number æKY PBUnmountVol æFp Files.p æT FUNCTION æTN $A00E æD FUNCTION PBUnmountVol(paramBlock: ParmBlkPtr): OSErr; æDT myVariable := PBUnmountVol(paramBlock); æRI PBUnmountVol function II-106, IV-134 æC Trap macro _UnmountVol Parameter block <-- 16 ioResult word --> 18 ioNamePtr pointer --> 22 ioVRefNum word PBUnmountVol unmounts the volume specified by ioNamePtr or ioVRefNum, by calling PBFlushVol to flush the volume, closing all open files on the volume, and releasing the memory used for the volume. PBUnmountVol is always executed synchronously. Warning: Don’t unmount the startup volume. Note: Unmounting a volume does not close working directories; to release the memory allocated to a working directory, call PBCloseWD. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY PBWrite æFp Files.p æT FUNCTION æTN $A003 æD FUNCTION PBWrite(paramBlock: ParmBlkPtr;async: BOOLEAN): OSErr; æDT myVariable := PBWrite(paramBlock,async); æRT 187 æRI PBWrite function IV-140 Device Manager II-185 File Manager II-110 æC •••Refer to Technical Note #187:••• Trap macro _Write Parameter block --> 12 ioCompletion pointer <-- 16 ioResult word --> 24 ioRefNum word --> 32 ioBuffer pointer --> 36 ioReqCount long word <-- 40 ioActCount long word --> 44 ioPosMode word <-> 46 ioPosOffset long word PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. After the write is completed, the mark is returned in ioPosOffset and the number of bytes actually written is returned in ioActCount. Result codes noErr No error dskFulErr Disk full fLckdErr File locked fnOpnErr File not open ioErr I/O error paramErr Negative ioReqCount posErr Attempt to position before start of file rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY rdVerify æFp Files.p æC To have the File Manager verify that all data written to a volume exactly matches the data in memory, make a Read call right after the Write call. The parameters for a read-verify operation are the same as for a standard Read call, except that the following constant must be added to the positioning mode: CONST rdVerify = 64; {read-verify mode} The result code ioErr is returned if any of the data doesn’t match. æKY Rename æFp Files.p æT FUNCTION æTN $A00B æD FUNCTION Rename(oldName: Str255;vRefNum: INTEGER;newName: Str255): OSErr; æDT myVariable := Rename(oldName,vRefNum,newName); æRI Rename function high-level II-96, IV-114 low-level II-118, IV-153 æC [Not in ROM] Given a file name in oldName, Rename changes the name of the file to newName. Access paths currently in use aren’t affected. Given a volume name in oldName or a volume reference number in vRefNum, Rename changes the name of the specified volume to newName. Warning: If you’re renaming a volume, be sure that both names end with a colon. Result codes noErr No error bdNamErr Bad file name dirFulErr Directory full dupFNErr Duplicate file name extFSErr External file system fLckdErr File locked fnfErr File not found fsRnErr Problem during rename ioErr I/O error nsvErr No such volume paramErr No default volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY RstFLock æFp Files.p æT FUNCTION æD FUNCTION RstFLock(fileName: Str255;vRefNum: INTEGER): OSErr; æDT myVariable := RstFLock(fileName,vRefNum); æRI RstFLock function II-96, IV-114 æC [Not in ROM] RstFLock unlocks the file having the name fileName on the specified volume. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY SetEOF æFp Files.p æT FUNCTION æTN $A012 æD FUNCTION SetEOF(refNum: INTEGER;logEOF: LONGINT): OSErr; æDT myVariable := SetEOF(refNum,logEOF); æRI SetEOF function P-132, 180 high-level II-93, IV-111 low-level II-112, IV-142 æC [Not in ROM] SetEOF sets the logical end-of-file of the open file whose access path is specified by refNum to the position specified by logEOF. If you attempt to set the logical end-of-file beyond the physical end-of-file, the physical end-of-file is set to one byte beyond the end of the next free allocation block; if there isn’t enough space on the volume, no change is made, and SetEOF returns dskFulErr as its function result. If logEOF is 0, all space occupied by the file on the volume is released. Result codes noErr No error dskFulErr Disk full extFSErr External file system fLckdErr File locked fnOpnErr File not open ioErr I/O error rfNumErr Bad reference number vLckdErr Software volume lock wPrErr Hardware volume lock wrPermErr Read/write permission doesn’t allow writing æKY SetFInfo æFp Files.p æT FUNCTION æD FUNCTION SetFInfo(fileName: Str255;vRefNum: INTEGER;fndrInfo: FInfo): OSErr; æDT myVariable := SetFInfo(fileName,vRefNum,fndrInfo); æRI SetFInfo function II-95, IV-114 æC [Not in ROM] For the file having the name fileName on the specified volume, SetFInfo sets information used by the Finder to fndrInfo (see the section “Information Used by the Finder”). Result codes noErr No error extFSErr External file system fLckdErr File locked fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY SetFLock æFp Files.p æT FUNCTION æD FUNCTION SetFLock(fileName: Str255;vRefNum: INTEGER): OSErr; æDT myVariable := SetFLock(fileName,vRefNum); æRI SetFLock function II-95, IV-114 æC [Not in ROM] SetFLock locks the file having the name fileName on the specified volume. Access paths currently in use aren’t affected. Result codes noErr No error extFSErr External file system fnfErr File not found ioErr I/O error nsvErr No such volume vLckdErr Software volume lock wPrErr Hardware volume lock æKY SetFPos æFp Files.p æT FUNCTION æTN $A044 æD FUNCTION SetFPos(refNum: INTEGER;posMode: INTEGER;posOff: LONGINT): OSErr; æDT myVariable := SetFPos(refNum,posMode,posOff); æRI SetFPos function P-131, 132, 180 high-level II-93, IV-110 low-level II-111, IV-141 æC [Not in ROM] SetFPos sets the mark of the open file whose access path is specified by refNum to the position specified by posMode and posOff (except when posMode is equal to fsAtMark, in which case posOff is ignored). PosMode indicates how to position the mark; it must contain one of the following values: CONST fsAtMark = 0; {at current mark} fsFromStart = 1; {set mark relative to beginning of file} fsFromLEOF = 2; {set mark relative to logical end-of-file} fsFromMark = 3; {set mark relative to current mark} If you specify fsAtMark, posOffset is ignored and the mark is left wherever it’s currently positioned. If you choose to set the mark (relative to either the beginning of the file, the logical end-of-file, or the current mark), posOffset specifies the byte offset from the chosen point (either positive or negative) where the mark should be set. If you try to set the mark past the logical end-of-file, SetFPos moves the mark to the end-of-file and returns eofErr as its function result. Result codes noErr No error eofErr End-of-file extFSErr External file system fnOpnErr File not open ioErr I/O error posErr Attempt to position before start of file rfNumErr Bad reference number æKY SetVol æFp Files.p æT FUNCTION æTN $A015 æD FUNCTION SetVol(volName: StringPtr;vRefNum: INTEGER): OSErr; æDT myVariable := SetVol(volName,vRefNum); æRI SetVol function high-level II-89, IV-107 low-level II-105, IV-132 æC [Not in ROM] SetVol sets the default volume to the mounted volume specified by volName or vRefNum. Result codes noErr No error bdNamErr Bad volume name nsvErr No such volume paramErr No default volume æKY UnmountVol æFp Files.p æT FUNCTION æTN $A00E æD FUNCTION UnmountVol(volName: StringPtr;vRefNum: INTEGER): OSErr; æDT myVariable := UnmountVol(volName,vRefNum); æRT 180 æRI UnmountVol function high-level II-90, IV-108 low-level II-106, IV-134 æC [Not in ROM] UnmountVol unmounts the volume specified by volName or vRefNum, by calling FlushVol to flush the volume buffer, closing all open files on the volume, and releasing the memory used for the volume. Warning: Don’t unmount the startup volume. Result codes noErr No error bdNamErr Bad volume name extFSErr External file system ioErr I/O error nsDrvErr No such drive nsvErr No such volume paramErr No default volume æKY VCB æFp Files.p æT RECORD æC VCB = RECORD qLink: QElemPtr; qType: INTEGER; vcbFlags: INTEGER; vcbSigWord: INTEGER; vcbCrDate: LONGINT; vcbLsMod: LONGINT; vcbAtrb: INTEGER; vcbNmFls: INTEGER; vcbVBMSt: INTEGER; vcbAllocPtr: INTEGER; vcbNmAlBlks: INTEGER; vcbAlBlkSiz: LONGINT; vcbClpSiz: LONGINT; vcbAlBlSt: INTEGER; vcbNxtCNID: LONGINT; vcbFreeBks: INTEGER; vcbVN: Str27; vcbDrvNum: INTEGER; vcbDRefNum: INTEGER; vcbFSID: INTEGER; vcbVRefNum: INTEGER; vcbMAdr: Ptr; vcbBufAdr: Ptr; vcbMLen: INTEGER; vcbDirIndex: INTEGER; vcbDirBlk: INTEGER; vcbVolBkUp: LONGINT; vcbVSeqNum: INTEGER; vcbWrCnt: LONGINT; vcbXTClpSiz: LONGINT; vcbCTClpSiz: LONGINT; vcbNmRtDirs: INTEGER; vcbFilCnt: LONGINT; vcbDirCnt: LONGINT; vcbFndrInfo: ARRAY [1..8] OF LONGINT; vcbVCSize: INTEGER; vcbVBMCSiz: INTEGER; vcbCtlCSiz: INTEGER; vcbXTAlBlks: INTEGER; vcbCTAlBlks: INTEGER; vcbXTRef: INTEGER; vcbCTRef: INTEGER; vcbCtlBuf: Ptr; vcbDirIDM: LONGINT; vcbOffsM: INTEGER; END; »Volume Control Blocks •••Refer to Technical Note #106:••• Each time a volume is mounted, its volume information is read from it and is used to build a new volume control block in the volume-control-block queue (unless an ejected or off-line volume is being remounted). A copy of the volume block map is also read from the volume and placed in the system heap, and a volume buffer is created in the system heap. The volume-control-block queue is a standard Operating System queue that’s maintained in the system heap. It contains a volume control block for each mounted volume. A volume control block is a 178-byte nonrelocatable block that contains volume-specific information. It has the following structure: TYPE VCB = RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} vcbFlags: INTEGER; {bit 15=1 if dirty} vcbSigWord: INTEGER; {$4244 for hierarchical, $D2D7 for flat} vcbCrDate: LONGINT; {date and time of initialization} vcbLsMod: LONGINT; {date and time of last modification} vcbAtrb: INTEGER; {volume attributes} vcbNmFls: INTEGER; {number of files in directory} vcbVBMSt: INTEGER; {first block of volume bit map} vcbAllocPtr: INTEGER; {used internally} vcbNmAlBlks: INTEGER; {number of allocation blocks} vcbAlBlkSiz: LONGINT; {allocation block size} vcbClpSiz: LONGINT; {default clump size} vcbAlBlSt: INTEGER; {first block in block map} vcbNxtCNID: LONGINT; {next unused directory ID or file number} vcbFreeBks: INTEGER; {number of unused allocation blocks} vcbVN: STRING[27]; {volume name} vcbDrvNum: INTEGER; {drive number} vcbDRefNum: INTEGER; {driver reference number} vcbFSID: INTEGER; {file-system identifier} vcbVRefNum: INTEGER; {volume reference number} vcbMAdr: Ptr; {pointer to block map} vcbBufAdr: Ptr; {pointer to volume buffer} vcbMLen: INTEGER; {number of bytes in block map} vcbDirIndex: INTEGER; {used internally} vcbDirBlk: INTEGER; {used internally} vcbVolBkUp: LONGINT; {date and time of last backup} vcbVSeqNum: INTEGER; {used internally} vcbWrCnt: LONGINT; {volume write count} vcbXTClpSiz: LONGINT; {clump size of extents tree file} vcbCTClpSiz: LONGINT; {clump size of catalog tree file} vcbNmRtDirs: INTEGER; {number of directories in root} vcbFilCnt: LONGINT; {number of files on volume} vcbDirCnt: LONGINT; {number of directories on volume} vcbFndrInfo: ARRAY[1..8] OF LONGINT; {information used by } { the Finder} vcbVCSize: INTEGER; {used internally} vcbVBMCSiz: INTEGER; {used internally} vcbCtlCSiz: INTEGER; {used internally} vcbXTAlBks: INTEGER; {size in blocks of extents tree file} vcbCTAlBks: INTEGER; {size in blocks of catalog tree file} vcbXTRef: INTEGER; {path reference number for extents } { tree file} vcbCTRef: INTEGER; {path reference number for catalog } { tree file} vcbCtlBuf: Ptr; {pointer to extents and catalog } { tree caches} vcbDirIDM: LONGINT; {directory last searched} vcbOffsM: INTEGER {offspring index at last search} END; 64K ROM note: A volume control block created for a flat volume is a subset of the above structure. It’s actually smaller and contains only the fields up to and including vcbDirBlk. In addition, the names of several fields have been changed to reflect the fact that they contain different information on hierarchical volumes: vcbLsBkUp, vcbDirSt, vcbBlLn, vcbNmBlks, and vcbNxtFNum have been changed to vcbLsMod, vcbVBMSt, vcbAllocPtr, vcbNmAlBlks, and vcbNxtCNID respectively. QLink points to the next entry in the queue, and qType indicates the queue type, which must always be ORD(fsQType). Bit 15 of vcbFlags is set if the volume information has been changed by a routine call since the volume was last affected by a FlushVol call. VCBLsMod contains the date and time that the volume was last modified (this is not necessarily when it was flushed). 64K ROM note: VCBLsMod replaces the field vcbLsBkUp from flat directory volumes. The name vcbLsBkUp was actually a misnomer; this field has always contained the date and time of the last modification, not the last backup. Another field, vcbVolBkUp, contains the date and time of the last backup. VCBAtrb contains the volume attributes, as follows: Bit Meaning 0–4 Set if inconsistencies were found between the volume information and the file directory when the volume was mounted 6 Set if volume is busy (one or more files are open) 7 Set if volume is locked by hardware 15 Set if volume is locked by software VCBVBMSt contains the number of the first block in the volume bit map; on flat volumes, it contains the first block of the file directory. VCBNmAlBlks contains the number of allocation blocks on the volume, and vcbFreeBks specifies how many of those blocks are unused. VCBAlBlSt is used only with flat volumes; it contains the number of the first block in the block map. VCBDrvNum contains the drive number of the drive on which the volume is mounted; vcbDRefNum contains the driver reference number of the driver used to access the volume. When a mounted volume is placed off-line, vcbDrvNum is cleared. When a volume is ejected, vcbDrvNum is cleared and vcbDRefNum is set to the negative of vcbDrvNum (becoming a positive number). VCBFSID identifies the file system handling the volume; it’s 0 for volumes handled by the File Manager, and nonzero for volumes handled by other file systems. When a volume is placed off-line, its buffer and bit map (or block map, in the case of flat directory volumes) are released. When a volume is unmounted, its volume control block is removed from the volume-control-block queue. You can get a pointer to the header of the volume-control-block queue by calling the File Manager function GetVCBQHdr. æKY FixMath.p æKL Fix2Frac Fix2Long Fix2X FixATan2 FixDiv Frac2Fix Frac2X FracCos FracDiv FracMul FracSin FracSqrt Long2Fix X2Fix X2Frac æKY Fix2Frac æFp FixMath.p æT FUNCTION æTN $A841 æD FUNCTION Fix2Frac(x: Fixed): Fract; æDT myVariable := Fix2Frac(x); æRI Fix2Frac function IV-65 æC Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY Fix2Long æFp FixMath.p æT FUNCTION æTN $A840 æD FUNCTION Fix2Long(x: Fixed): LONGINT; æDT myVariable := Fix2Long(x); æRI Fix2Long function IV-65 æC Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY Fix2X æFp FixMath.p æT FUNCTION æTN $A843 æD FUNCTION Fix2X(x: Fixed): Extended; æDT myVariable := Fix2X(x); æRI Fix2X function IV-65 æC Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended floating-point type. These functions do not set floating-point exception flags. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY FixATan2 æFp FixMath.p æT FUNCTION æTN $A818 æD FUNCTION FixATan2(x: LONGINT;y: LONGINT): Fixed; æDT myVariable := FixATan2(x,y); æRI FixATan2 function IV-65 æC FixATan2 returns the arctangent of y / x in radians. Note that FixATan2 effects “arctan(type / type) --> Fixed”: arctan(LONGINT / LONGINT) --> Fixed arctan(Fixed / Fixed) --> Fixed arctan(Fract / Fract) --> Fixed æKY FixDiv æFp FixMath.p æT FUNCTION æTN $A84D æD FUNCTION FixDiv(x: Fixed;y: Fixed): Fixed; æDT myVariable := FixDiv(x,y); æRI FixDiv function IV-64 æC FixDiv returns x / y. Note that FixDiv effects “type / type --> Fixed” and “type / Fixed --> type”: Fixed / Fixed --> Fixed LONGINT / LONGINT --> Fixed Fract / Fract --> Fixed LONGINT / Fixed --> LONGINT Fract / Fixed --> Fract æKY Frac2Fix æFp FixMath.p æT FUNCTION æTN $A842 æD FUNCTION Frac2Fix(x: Fract): Fixed; æDT myVariable := Frac2Fix(x); æRI Frac2Fix function IV-65 æC Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY Frac2X æFp FixMath.p æT FUNCTION æTN $A845 æD FUNCTION Frac2X(x: Fract): Extended; æDT myVariable := Frac2X(x); æRI Frac2X function IV-65 æC Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended floating-point type. These functions do not set floating-point exception flags. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY FracCos æFp FixMath.p æT FUNCTION æTN $A847 æD FUNCTION FracCos(x: Fixed): Fract; æDT myVariable := FracCos(x); æRI FracCos function IV-64 æC FracCos and FracSin return the cosine and sine of their radian arguments, respectively. The hexadecimal value 0.C910 (which is FixATan2(1,1)) is the approximation to π/4 used for argument reduction. Thus, FracCos and FracSin are nearly periodic, but with period 2*P instead of 2*π, where P=3.1416015625 and π, of course, is 3.14159265.... æKY FracDiv æFp FixMath.p æT FUNCTION æTN $A84B æD FUNCTION FracDiv(x: Fract;y: Fract): Fract; æDT myVariable := FracDiv(x,y); æRI FracDiv function IV-64 æC FracDiv returns x / y. Note that FracDiv effects “type / type --> Fract” and “type / Fract --> type”: Fract / Fract --> Fract LONGINT / LONGINT --> Fract Fixed / Fixed --> Fract LONGINT / Fract --> LONGINT Fixed / Fract --> Fixed æKY FracMul æFp FixMath.p æT FUNCTION æTN $A84A æD FUNCTION FracMul(x: Fract;y: Fract): Fract; æDT myVariable := FracMul(x,y); æRI FracMul function IV-64 æC FracMul returns x * y. Note that FracMul effects “type * Fract --> type”: Fract * Fract --> Fract LONGINT * Fract --> LONGINT Fract * LONGINT --> LONGINT Fixed * Fract --> Fixed Fract * Fixed --> Fixed æKY FracSin æFp FixMath.p æT FUNCTION æTN $A848 æD FUNCTION FracSin(x: Fixed): Fract; æDT myVariable := FracSin(x); æRI FracSin function IV-64 æC FracCos and FracSin return the cosine and sine of their radian arguments, respectively. The hexadecimal value 0.C910 (which is FixATan2(1,1)) is the approximation to π/4 used for argument reduction. Thus, FracCos and FracSin are nearly periodic, but with period 2*P instead of 2*π, where P=3.1416015625 and π, of course, is 3.14159265.... æKY FracSqrt æFp FixMath.p æT FUNCTION æTN $A849 æD FUNCTION FracSqrt(x: Fract): Fract; æDT myVariable := FracSqrt(x); æRI FracSqrt function IV-64 æC FracSqrt returns the square root of x, with x interpreted as unsigned in the range 0 through 4–(2–30), inclusive: That is, bit 15 in Figure 1 has weight 2 rather than –2. The result, too, is unsigned in the range 0 through 2, inclusive. æKY Long2Fix æFp FixMath.p æT FUNCTION æTN $A83F æD FUNCTION Long2Fix(x: LONGINT): Fixed; æDT myVariable := Long2Fix(x); æRI Long2Fix function IV-65 æC Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY X2Fix æFp FixMath.p æT FUNCTION æTN $A844 æD FUNCTION X2Fix(x: Extended): Fixed; æDT myVariable := X2Fix(x); æRI X2Fix function IV-65 æC Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended floating-point type. These functions do not set floating-point exception flags. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY X2Frac æFp FixMath.p æT FUNCTION æTN $A846 æD FUNCTION X2Frac(x: Extended): Fract; æDT myVariable := X2Frac(x); æRI X2Frac function IV-65 æC Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended floating-point type. These functions do not set floating-point exception flags. Examples Examples of the use of these fixed-point functions are provided below; all numbers are decimal unless otherwise noted. Function Result Comment FixDiv (X2Fix(1.95), X2Fix(1.30)) $00018000 1.5 = 01.10 bin FracDiv (X2Frac(1.95), X2Frac(1.30)) $60000000 1.5 = 01.10 bin FracMul (X2Frac(1.50), X2Frac(1.30)) $7CCCCCCD 1.95 rounded FracSqrt (X2Frac(1.96)) $5999999A 1.4 rounded FracSin (X2Fix(3.1416015625)) $00000000 0 FracCos (X2Fix(3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(1.75)) $00000002 2 Fix2Frac (X2Fix(1.75)) $70000000 1.75 = 01.11 bin Frac2Fix (X2Frac(1.75)) $0001C000 1.75 = 01.11 bin FixATan2 (X2Fix(1.00), X2Fix(1.00)) $0000C910 0.C910 hex = X2Fix (π/4) FixDiv (X2Fix(-1.95), X2Fix(1.30)) $FFFE8000 -1.5 FracDiv (X2Frac(-1.95), X2Frac(1.30)) $A0000000 -1.5 FracMul (X2Frac(-1.50), X2Frac(1.30)) $83333333 -1.95 rounded FracSin (X2Fix(-3.1416015625)) $00000000 0 FracCos (X2Fix(-3.1416015625)) $C0000000 -1 Fix2Long (X2Fix(-1.75)) $FFFFFFFE -2 Fix2Frac (X2Fix(-1.75)) $90000000 -1.75 Frac2Fix (X2Frac(-1.75)) $FFFE4000 -1.75 FixATan2 (X2Fix(-1.00), X2Fix(-1.00)) $FFFDA4D0 -3*X2Fix(π/4)=3*0.C910 hex æKY Fonts.p æKL FMSwapFont FontMetrics GetFNum GetFontName InitFonts RealFont SetFontLock SetFractEnable SetFScaleDisable appleMark applFont AsscEntry athens cairo checkMark commandMark courier diamondMark FamRec fixedFont FMetricRec FMInput FMOutPtr FMOutput FontAssoc FontRec fontWid fxdFntH fxdFntHW fxdFntW geneva helvetica InitFonts InitFonts KernEntry KernPair KernTable london losAngeles mobile monaco NameTable newYork propFont prpFntH prpFntHW prpFntW sanFran StyleTable symbol systemFont taliesin times toronto venice WidEntry WidthTable æKY FMOutput,FMOutPtr æFp Fonts.p æT TYPE æC FMOutPtr = ^FMOutput; FMOutput = PACKED RECORD errNum: INTEGER; fontHandle: Handle; bold: Byte; italic: Byte; ulOffset: Byte; ulShadow: Byte; ulThick: Byte; shadow: Byte; extra: SignedByte; ascent: Byte; descent: Byte; widMax: Byte; leading: SignedByte; unused: Byte; numer: Point; denom: Point; END; Based on the information in the font characterization table, the Font Manager determines the optimum ascent, descent, and leading, so that the highest-quality printing or drawing available will be produced. It then stores this information in a font output record: TYPE FMOutput = PACKED RECORD errNum: INTEGER; {not used} fontHandle: Handle; {handle to font record} bold: Byte; {bold factor} italic: Byte; {italic factor} ulOffset: Byte; {underline offset} ulShadow: Byte; {underline shadow} ulThick: Byte; {underline thickness} shadow: Byte; {shadow factor} extra: SignedByte; {width of style} ascent: Byte; {ascent} descent: Byte; {descent} widMax: Byte; {maximum character width} leading: SignedByte; {leading} unused: Byte; {not used} numer: Point; {numerators of scaling factors} denom: Point {denominators of scaling factors} END; ErrNum is reserved for future use, and is set to 0. FontHandle is a handle to the font record of the font, as described in the next section. Bold, italic, ulOffset, ulShadow, ulThick, and shadow are all fields that modify the way stylistic variations are done; their values are taken from the font characterization table, and are used by QuickDraw. (You’ll need to experiment with these values if you want to determine exactly how they’re used.) Extra indicates the number of pixels that each character has been widened by stylistic variation. For example, using the screen values shown in Figure 22, the extra field for bold shadowed characters would be 3. Ascent, descent, widMax, and leading are the same as the fields of the FontInfo record returned by the QuickDraw procedure GetFontInfo. Numer and denom contain the scaling factors. Just before returning this record to QuickDraw, the Font Manager calls the device driver’s control routine to allow the driver to make any final modifications to the record. Finally, the font information is returned to QuickDraw via a pointer to the record, defined as follows: TYPE FMOutPtr = ^FMOutput; Note: If you want to make your own calls to the device driver’s Control function, the reference number must be the driver reference number from the font input record’s device field, csCode must be 8, csParam must be a pointer to the font output record, and csParam+4 must be the value of the font input record’s device field. æKY AsscEntry æFp Fonts.p æT RECORD æC AsscEntry = RECORD fontSize: INTEGER; fontStyle: INTEGER; fontID: INTEGER; {font resource ID} END; æKY commandMark,checkMark,diamondMark,appleMark æFp Fonts.p æC _______________________________________________________________________________ »CHARACTERS IN A FONT _______________________________________________________________________________ Note: The information on the Characters In A Font described in the following paragraphs was originally documented in Inside Macintosh, Volume I. A font can consist of up to 255 distinct characters; not all characters need to be defined in a single font. Figure 20 shows the standard printing characters on the Macintosh and their ASCII codes (for example, the ASCII code for “A” is 41 hexadecimal, or 65 decimal). Note: Codes $00 through $1F and code $7F are normally nonprinting characters (see the Toolbox Event Manager chapter for details). The special characters in the system font with codes $11 through $14 can’t normally be typed from the keyboard or keypad. The Font Manager defines constants for these characters: CONST commandMark = $11; {Command key symbol} checkMark = $12; {check mark} diamondMark = $13; {diamond symbol} appleMark = $14; {apple symbol} In addition to its maximum of 255 characters, every font contains a missing symbol that’s drawn in case of a request to draw a character that’s missing from the font. •••Refer to Figure 20.••• Figure 20–Font Characters æKY FamRec æFp Fonts.p æT RECORD æC FamRec = RECORD ffFlags: INTEGER; {flags for family} ffFamID: INTEGER; {family ID number} ffFirstChar: INTEGER; {ASCII code of 1st character} ffLastChar: INTEGER; {ASCII code of last character} ffAscent: INTEGER; {maximum ascent for 1pt font} ffDescent: INTEGER; {maximum descent for 1pt font} ffLeading: INTEGER; {maximum leading for 1pt font} ffWidMax: INTEGER; {maximum widMax for 1pt font} ffWTabOff: LONGINT; {offset to width table} ffKernOff: LONGINT; {offset to kerning table} ffStylOff: LONGINT; {offset to style mapping table} ffProperty: ARRAY [1..9] OF INTEGER; {style property info} ffIntl: ARRAY [1..2] OF INTEGER; {for international use} ffVersion: INTEGER; {version number} END; »Family Records Note: The extensions to the Font Manager described in the following paragraphs were originally documented in Inside Macintosh, Volume IV. As such, this information refers to the 128K ROMs and System file version 3.2 and later. Assembly-language note: The global variable LastFOND is a handle to the last family record used. You can read the contents of the family record by using this handle. You should not alter the contents of this record. The data type for a family record is as follows: TYPE FamRec = RECORD ffFlags: INTEGER; {flags for family} ffFamID: INTEGER; {family ID number} ffFirstChar: INTEGER; {ASCII code of the first character} ffLastChar: INTEGER; {ASCII code of the last character} ffAscent: INTEGER; {maximum ascent for 1-pt.font} ffDescent: INTEGER; {maximum descent for 1-pt.font} ffLeading: INTEGER; {maximum leading for 1-pt.font} ffWidMax: INTEGER; {maximum width for 1-pt.font} ffWTabOff: LONGINT; {offset to width table} ffKernOff: LONGINT; {offset to kerning table} ffStylOff: LONGINT; {offset to style-mapping table} ffProperty: ARRAY[1..9] OF INTEGER; {style property info} ffIntl: ARRAY[1..2] OF INTEGER; {reserved} ffVersion: INTEGER; {version number} { ffAssoc: FontAssoc;} {font association table} { ffWidthTab: WidTable;} {width table} { ffStyTab: StyleTable;}{style-mapping table} { ffKernTab: KernTable;} {kerning table} END; Note: The variable-length arrays appear as comments because they’re not valid Pascal syntax; they’re used only as conceptual aids. This version of the FamRec is accurate for Volume IV; the extensions to the FamRec made in Volume V are not included here. The ffFlags field defines general characteristics of the font family, as follows: Bit Meaning 0 Set if there’s an image-height table 1 Set if there’s a character-width table 2–11 Reserved (should be zero) 12 Set to ignore FractEnable when deciding whether to use fixed-point values for stylistic variations (see bit 13), clear to treat FractEnable as usual 13 Set to use integer extra width for stylistic variations, clear to compute fixed-point extra width from the family style-mapping table when FractEnable is TRUE 14 Set if family fractional-width table is not used, clear if table is used 15 Set for fixed-width font, clear for proportional font The values in the ffAscent, ffDescent, ffLeading, and ffWidMax describe the maximum dimensions of the family as they would be for a hypothetical one-point font to be scaled up. They use a special 16-bit fixed-point format with an integer part in the high-order 4 bits and a fractional part in the low-order 12 bits. The FontMetrics procedure calculates the true values by multiplying this number by the actual point size. The ffWTabOff, ffKernOff, and ffStylOff fields are offsets from the top of the record to the start of the width table, kerning table, and style-mapping table, respectively; if any of these fields is zero, the corresponding table does not exist. The ffProperty field is the family style-property table, shown in Figure 11. •••Refer to Figure 11.••• Figure 11–Family Style-Property Table Each entry is a 16-bit fixed-point number with a signed integer part in the high-order 4 bits and a fractional part in the low-order 12 bits. These numbers are used to calculate the amount of extra width for special stylistic variations; each of these values is multiplied by the point size of the font actually being used. If the font already exists for a given style, the value in its field is ignored. The ffAssoc field contains the font association table. This table, shown in Figure 12, is used to match a given font size and style combination with the resource ID of an actual font. •••Refer to Figure 12.••• Figure 12–Font Association Table Note: In order to reduce search time, the Font Manager requires that the entries be sorted according to the fontSize field, with the smallest sizes first. If multiple fonts from the same family, the plain (roman) fonts come first. The Font Manager is optimized to look first for 'NFNT' resources, then 'FONT' resources. Each entry in the font association table has the format shown in Figure 13. •••Refer to Figure 13.••• Figure 13–Font Association Table Entry The font association table is followed by the family character-width table. As shown in Figure 14, this table is actually a number of width tables (since a font family may include numerous styles). •••Refer to Figure 14.••• Figure 14–Family Character-Width Table Each character-width table is preceded by a style code; the low-order byte of this word specifies stylistic variations (see Figure 15). The widths in each table are for a hypothetical one-point font; the actual values for the characters are calculated by multiplying these widths by the font size. The widths in this table are stored in a 16-bit fixed-point format with an unsigned integer part in the high-order 4 bits and a fractional part in the low-order 12 bits. •••Refer to Figure 15.••• Figure 15–Style Codes The style-mapping table and its associated tables are used by the LaserWriter driver and are described in the Apple LaserWriter Reference. The kerning table, like the family character-width table, is actually a number of kerning tables (see Figure 16). •••Refer to Figure 16.••• Figure 16–Kerning Table Each kerning table is preceded by a style code; stored in the low-order byte of the word, this style information has the same format shown in Figure 15 above. The number of entries in the table follows the style word (see Figure 17). •••Refer to Figure 17.••• Figure 17–Structure of a Kerning Table The entries in each kerning table (shown in Figure 18) consist of a pair of characters followed by a kerning offset for a hypothetical one-point font. This value, represented by an integer part in the high-order 4 bits and a fractional part in the low-order 12 bits, is multiplied by the size of the font to obtain the actual offset. •••Refer to Figure 18.••• Figure 18–Kerning Table Entry Note: The extensions to the Font Manager described in the following paragraphs were originally documented in Inside Macintosh, Volume V. As such, this information refers to the Macintosh SE and Macintosh II ROMs and System file version 4.1 and later. For Macintosh II only, bits 8 and 9 of the font style word within each font association table specify the font depth; they must contain the same value as bits 2 and 3 of the fontType field of the font record. All other undefined bits remain 0. A font family is stored as a resource of type 'FOND', and with the Macintosh II, it’s format has been extended. The new format is the following (with extension fields indicated by asterisks): Number of bytes Contents 2 bytes FONDFlags field of family record 2 bytes FONDFamID field of family record 2 bytes FONDFirst field of family record 2 bytes FONDLast field of family record 2 bytes FONDAscent field of family record 2 bytes FONDDescent field of family record 2 bytes FONDLeading field of family record 2 bytes FONDWidMax field of family record 4 bytes FONDWTabOff of family record 4 bytes FONDKernOff of family record 4 bytes FONDStylOff of family record 24 bytes FONDProperty field of family record 4 bytes FONDIntl field of family record 2 bytes *Version number ($02) m bytes FONDAssoc field of family record (variable length) 2 bytes *Number of offsets minus 1 4 bytes *Offset to bounding box table n bytes *Bounding box table p bytes FONDWidTable field of family record (variable length) q bytes FONDStylTab field of family record (variable length) r bytes FONDKerntab field of family record (variable length) The bounding box table has an entry for each style available in the family. The table as a whole has this form: Number of bytes Contents 2 bytes Number of entries minus 1 10 bytes First entry 10 bytes Second entry . . . Each bounding box entry has this form, giving the bounding box position with respect to the origin of the characters: Number of bytes Contents 2 bytes Style word 2 bytes Lower left x coordinate 2 bytes Lower left y coordinate 2 bytes Upper right x coordinate 2 bytes Upper right y coordinate Note: The extensions to the Font Manager described in the following paragraphs were originally documented in Inside Macintosh, Volume IV. As such, this information refers to the 128K ROMs and System file version 3.2 and later. æKY FMetricRec æFp Fonts.p æT RECORD æC FMetricRec = RECORD ascent: Fixed; {base line to top} descent: Fixed; {base line to bottom} leading: Fixed; {leading between lines} widMax: Fixed; {maximum character width} wTabHandle: Handle; {handle to font width table} END; æKY FMInput æFp Fonts.p æT PACKED RECORD æC FMInput = PACKED RECORD family: INTEGER; size: INTEGER; face: Style; needBits: BOOLEAN; device: INTEGER; numer: Point; denom: Point; END; _______________________________________________________________________________ »COMMUNICATION BETWEEN QUICKDRAW AND THE FONT MANAGER _______________________________________________________________________________ This section describes the data structures that allow QuickDraw and the Font Manager to exchange information. It also discusses the communication that may occur between the Font Manager and the driver of the device on which the characters are being drawn or printed. You can skip this section if you want to change fonts, character style, and font sizes by calling QuickDraw and aren’t interested in the lower-level data structures and routines of the Font Manager. To understand this section fully, you’ll have to be familiar with device drivers and the Device Manager. Whenever you call a QuickDraw routine that does anything with text, QuickDraw requests information from the Font Manager about the characters. The Font Manager performs any necessary calculations and returns the requested information to QuickDraw. As illustrated in Figure 21, this information exchange occurs via two data structures, a font input record (type FMInput) and a font output record (type FMOutput). First, QuickDraw passes the Font Manager a font input record: TYPE FMInput = PACKED RECORD family: INTEGER; {font number} size: INTEGER; {font size} face: Style; {character style} needBits: BOOLEAN; {TRUE if drawing} device: INTEGER; {device-specific information} numer: Point; {numerators of scaling factors} denom: Point {denominators of scaling factors} END; The first three fields contain the font number, size, and character style that QuickDraw wants to use. The needBits field indicates whether the characters actually will be drawn or not. If the characters are being drawn, all of the information describing the font, including the bit image comprising the characters, will be read into memory. If the characters aren’t being drawn and there’s a resource consisting of only the character widths and general font information, that resource will be read instead. The high-order byte of the device field contains a device driver reference number. From the driver reference number, the Font Manager can determine the optimum stylistic variations on the font to produce the highest-quality printing or drawing available on a device (as explained below). The low-order byte of the device field is ignored by the Font Manager but may contain information used by the device driver. •••Refer to Figure 21.••• Figure 21–Communication About Fonts The numer and denom fields contain the scaling factors to be used; numer.v divided by denom.v gives the vertical scaling, and numer.h divided by denom.h gives the horizontal scaling. The Font Manager takes the font input record and asks the Resource Manager for the font. If the requested size isn’t available, the Font Manager scales another size to match (as described under “Font Scaling”). Then the Font Manager gets the font characterization table via the device field. If the high-order byte of the device field is 0, the Font Manager gets the screen’s font characterization table (which is stored in the Font Manager). If the high-order byte of the device field is nonzero, the Font Manager calls the status routine of the device driver having that reference number, and the status routine returns a font characterization table. The status routine may use the value of the low-order byte of the device field to determine the font characterization table it should return. Note: If you want to make your own calls to the device driver’s Status function, the reference number must be the driver reference number from the font input record’s device field, csCode must be 8, csParam must be a pointer to where the device driver should put the font characterization table, and csParam+4 must be an integer containing the value of the font input record’s device field. Figure 22 shows the structure of a font characterization table and, on the right, the values it contains for the Macintosh screen. •••Refer to Figure 22.••• Figure 22–Font Characterization Table The first two words of the font characterization table contain the approximate number of dots per inch on the device. These values are only used for scaling between devices; they don’t necessarily correspond to a device’s actual resolution. The remainder of the table consists of three-byte triplets providing information about the different stylistic variations. For all but the triplet defining the underline characteristics: • The first byte in the triplet indicates which byte beyond the bold field of the font output record (see below) is affected by the triplet. • The second byte contains the amount to be stored in the affected field. • The third byte indicates the amount by which the extra field of the font output record is to be incremented (starting from 0). The triplet defining the underline characteristics indicates the amount by which the font output record’s ulOffset, ulShadow, and ulThick fields (respectively) should be incremented. æKY FMSwapFont æFp Fonts.p æT FUNCTION æTN $A901 æD FUNCTION FMSwapFont(inRec: FMInput): FMOutPtr; æDT myVariable := FMSwapFont(inRec); æMM æRI FMSwapFont function I-223 æC The following low-level routine is called by QuickDraw and won’t normally be used by an application directly, but it may be of interest to advanced programmers who want to bypass the QuickDraw routines that deal with text. FUNCTION FMSwapFont (inRec: FMInput) : FMOutPtr; FMSwapFont returns a pointer to a font output record containing the size, style, and other information about an adapted version of the font requested in the given font input record. (Font input and output records are explained in the following section.) FMSwapFont is called by QuickDraw every time a QuickDraw routine that does anything with text is used. If you want to call FMSwapFont yourself, you must build a font input record and then use the pointer returned by FMSwapFont to access the resulting font output record. æKY FontAssoc æFp Fonts.p æT RECORD æC FontAssoc = RECORD numAssoc: INTEGER; {number of entries - 1} END; æKY FontMetrics æFp Fonts.p æT PROCEDURE æTN $A835 æD PROCEDURE FontMetrics(theMetrics: FMetricRec); æDT FontMetrics(theMetrics); æMM æRI FontMetrics procedure IV-32 æC Note: The extensions to the Font Manager described in the following paragraphs were originally documented in Inside Macintosh, Volume IV. As such, this information refers to the 128K ROMs and System file version 3.2 and later. To improve the speed and readability of text display in your application, use the SetFractEnable and SetFScaleDisable procedures to enable fractional character widths and disable font scaling. Certain applications do not work properly when fractional character widths are used and font scaling is disabled, so these features are turned off by default. The FontMetrics function is much like QuickDraw’s GetFontInfo function except that it returns fixed-point values, letting you draw characters in more precise locations on the screen. If there’s a 'FOND' resource associated with the most recently drawn font, making the font resource purgeable or unpurgeable with the SetFontLock procedure will make the 'FOND' resource resource purgeable or unpurgeable as well. PROCEDURE FontMetrics (VAR theMetrics: FMetricRec); FontMetrics is similar to the QuickDraw procedure GetFontInfo except that it returns fixed-point values for greater accuracy in high-resolution printing. The FMetricRec data structure is defined as follows: TYPE FMetricRec = RECORD ascent: Fixed; {ascent} descent: Fixed; {descent} leading: Fixed; {leading} widMax: Fixed; {maximum character width} wTabHandle: Handle; {handle to global width table} END; Ascent, descent, leading, and widMax are identical in function to their counterparts in GetFontInfo. WTabHandle is a handle to the global width table (described below). æKY FontRec æFp Fonts.p æT RECORD æC FontRec = RECORD fontType: INTEGER; {font type} firstChar: INTEGER; {ASCII code of first character} lastChar: INTEGER; {ASCII code of last character} widMax: INTEGER; {maximum character width} kernMax: INTEGER; {negative of maximum character kern} nDescent: INTEGER; {negative of descent} fRectWidth: INTEGER; {width of font rectangle} fRectHeight: INTEGER; {height of font rectangle} owTLoc: INTEGER; {offset to offset/width table} ascent: INTEGER; {ascent} descent: INTEGER; {descent} leading: INTEGER; {leading} rowWords: INTEGER; {row width of bit image / 2 } END; »Font Records The information describing a font is contained in a data structure called a font record, which contains the following: • the font type (fixed-width or proportional) • the ASCII code of the first character and the last character in the font • the maximum character width and maximum amount any character kerns • the font height, ascent, descent, and leading • the bit image of the font • a location table, which is an array of words specifying the location of each character image within the bit image • an offset/width table, which is an array of words specifying the character offset and character width for each character in the font For every character, the location table contains a word that specifies the bit offset to the location of that character’s image in the bit image. The entry for a character missing from the font contains the same value as the entry for the next character. The last word of the table contains the offset to one bit beyond the end of the bit image (that is, beyond the character image for the missing symbol). The image width of each character is determined from the location table by subtracting the bit offset to that character from the bit offset to the next character in the table. There’s also one word in the offset/width table for every character: The high-order byte specifies the character offset and the low order byte specifies the character width. Missing characters are flagged in this table by a word value of –1. The last word is also –1, indicating the end of the table. Note: The 64K ROM version of the Resource Manager limits the total space occupied by the bit image, location table, offset/width table, and character-width and image-height tables to 32K bytes. For this reason, the practical limit on the font size of a full font is about 40 points. Figure 9 illustrates a sample location table and offset/width table corresponding to the bit image in Figure 8 above. A font record is referred to by a handle that you can get by calling the FMSwapFont function or the Resource Manager function GetResource. The data type for a font record is as follows: TYPE FontRec = RECORD fontType: INTEGER; {font type} firstChar: INTEGER; {ASCII code of first character} lastChar: INTEGER; {ASCII code of last character} widMax: INTEGER; {maximum character width} kernMax: INTEGER; {negative of maximum character kern} nDescent: INTEGER; {negative of descent} fRectWidth: INTEGER; {width of font rectangle} fRectHeight: INTEGER; {height of font rectangle} owTLoc: INTEGER; {offset to offset/width table} ascent: INTEGER; {ascent} descent: INTEGER; {descent} leading: INTEGER; {leading} rowWords: INTEGER; {row width of bit image / 2} { bitImage: ARRAY[1..rowWords,1..fRectHeight] OF INTEGER; } {bit image} { locTable: ARRAY[firstChar..lastChar+2] OF INTEGER; } {location table} { owTable: ARRAY[firstChar..lastChar+2] OF INTEGER; } {offset/width table} END; Note: The variable-length arrays appear as comments because they’re not valid Pascal syntax; they’re used only as conceptual aids. •••Refer to Figure 9.••• Figure 9–Sample Location Table and Offset/Width Table The fontType field must contain one of the following predefined constants: CONST propFont = $9000; {proportional font} fixedFont = $B000; {fixed-width font} The values in the widMax, kernMax, nDescent, fRectWidth, fRectHeight, ascent, descent, and leading fields all specify a number of pixels. KernMax indicates the largest number of pixels any character kerns, that is, the distance from the character origin to the left edge of the font rectangle. It should always be 0 or negative, since the kerned pixels are to the left of the character origin. NDescent is the negative of the descent (the distance from the character origin to the bottom of the font rectangle). The owTLoc field contains a word offset from itself to the offset/width table; it’s equivalent to 4 + (rowWords * fRectHeight) + (lastChar–firstChar+3) + 1 Warning: Remember, the offset and row width in a font record are given in words, not bytes. Assembly-language note: The global variable ROMFont0 contains a handle to the font record for the system font. Every size of a font is stored as a separate resource. The resource type for a font is 'FONT'. The resource data for a font is simply a font record: Number of bytes Contents 2 bytes FontType field of font record 2 bytes FirstChar field of font record 2 bytes LastChar field of font record 2 bytes WidMax field of font record 2 bytes KernMax field of font record 2 bytes NDescent field of font record 2 bytes FRectWidth field of font record 2 bytes FRectHeight field of font record 2 bytes OWTLoc field of font record 2 bytes Ascent field of font record 2 bytes Descent field of font record 2 bytes Leading field of font record 2 bytes RowWords field of font record n bytes Bit image of font n = 2 * rowWords * fRectHeight m bytes Location table of font m = 2 * (lastChar–firstChar+3) m bytes Offset/width table of font m = 2 * (lastChar–firstChar+3) As shown in Figure 10, the resource ID of a font has the following format: Bits 0-6 are the font size, bits 7-14 are the font number, and bit 15 is 0. Thus the resource ID corresponding to a given font number and size is (128 * font number) + font size •••Refer to Technical Note #245:••• Since 0 is not a valid font size, the resource ID having 0 in the size field is used to provide only the name of the font: The name of the resource is the font name. For example, for a font named Griffin and numbered 200, the resource naming the font would have a resource ID of 25600 and the resource name 'Griffin'. Size 10 of that font would be stored in a resource numbered 25610. •••Refer to Figure 10.••• Figure 10–Resource ID for a Font The resource type 'FRSV' is reserved by the Font Manager; it identifies fonts used by the system. Fonts whose resource IDs are contained in a 'FRSV' resource 1 will not be removed from the system resource file by the Font/DA Mover. The format of a 'FRSV' resource is as follows: Number of bytes Contents 2 bytes Number of font resource IDs n * 2 bytes n font resource IDs æKY GetFNum æFp Fonts.p æT PROCEDURE æTN $A900 æD PROCEDURE GetFNum(theName: Str255;VAR familyID: INTEGER); æDT GetFNum(theName,familyID); æMM æRT 191 æRI GetFNum procedure I-223 æC Warning: Before returning, the routines in this section issue the Resource Manager call SetResLoad(TRUE). If your program previously called SetResLoad(FALSE) and you still want that to be in effect after calling one of these Font Manager routines, you’ll have to call SetResLoad(FALSE) again. GetFNum returns in theNum the font number for the font having the given fontName. If there’s no such font, GetFNum returns 0. æKY GetFontName æFp Fonts.p æT PROCEDURE æTN $A8FF æD PROCEDURE GetFontName(familyID: INTEGER;VAR theName: Str255); æDT GetFontName(familyID,theName); æMM æRT 191 æRI GetFontName procedure I-223 æC Warning: Before returning, the routines in this section issue the Resource Manager call SetResLoad(TRUE). If your program previously called SetResLoad(FALSE) and you still want that to be in effect after calling one of these Font Manager routines, you’ll have to call SetResLoad(FALSE) again. PROCEDURE GetFontName (fontNum: INTEGER; VAR theName: Str255); Assembly-language note: The macro you invoke to call GetFontName from assembly language is named _GetFName. GetFontName returns in theName the name of the font having the font number fontNum. If there’s no such font, GetFontName returns the empty string. æKY InitFonts æFp Fonts.p æT PROCEDURE æTN $A8FE æD PROCEDURE InitFonts; æDT InitFonts; æMM æRT 72 æRI InitFonts procedure I-222, P-31, 95, 101, 107, 112, 118, 174 æC InitFonts initializes the Font Manager. If the system font isn’t already in memory, InitFonts reads it into memory. Call this procedure once before all other Font Manager routines or any Toolbox routine that will call the Font Manager. æKY KernEntry æFp Fonts.p æT RECORD æC KernEntry = RECORD kernLength: INTEGER; {length of this entry} kernStyle: INTEGER; {style the entry applies to} END; æKY KernPair æFp Fonts.p æT RECORD æC KernPair = RECORD kernFirst: CHAR; {1st character of kerned pair} kernSecond: CHAR; {2nd character of kerned pair} kernWidth: INTEGER; {kerning in 1pt fixed format} END; æKY KernTable æFp Fonts.p æT RECORD æC KernTable = RECORD numKerns: INTEGER; {number of kerning entries} END; æKY mobile æFp Fonts.p æC mobile = 24; æKY NameTable æFp Fonts.p æT RECORD æC NameTable = RECORD stringCount: INTEGER; baseFontName: Str255; END; æKY propFont,prpFntH,prpFntW,prpFntHW,fixedFont,fxdFntH,fxdFntW,fxdFntHW,fontWid æFp Fonts.p æC { Font types [Volume IV addition]} propFont = $9000; {proportional font} prpFntH = $9001; { with height table} prpFntW = $9002; { with width table} prpFntHW = $9003; { with height & width tables} fixedFont = $B000; {fixed-width font} fxdFntH = $B001; { with height table} fxdFntW = $B002; { with width table} fxdFntHW = $B003; { with height & width tables} fontWid = $ACB0; {font width data: 64K ROM only} æKY RealFont æFp Fonts.p æT FUNCTION æTN $A902 æD FUNCTION RealFont(fontNum: INTEGER;size: INTEGER): BOOLEAN; æDT myVariable := RealFont(fontNum,size); æMM æRI RealFont function I-223 æC Warning: Before returning, the routines in this section issue the Resource Manager call SetResLoad(TRUE). If your program previously called SetResLoad(FALSE) and you still want that to be in effect after calling one of these Font Manager routines, you’ll have to call SetResLoad(FALSE) again. RealFont returns TRUE if the font having the font number fontNum is available in the given size in a resource file, or FALSE if the font has to be scaled to that size. Note: RealFont will always return FALSE if you pass applFont in fontNum. To find out if the application font is available in a particular size, call GetFontName and then GetFNum to get the actual font number for the application font, and then call RealFont with that number. æKY SetFontLock æFp Fonts.p æT PROCEDURE æTN $A903 æD PROCEDURE SetFontLock(lockFlag: BOOLEAN); æDT SetFontLock(lockFlag); æMM æRI SetFontLock procedure I-223 æC SetFontLock applies to the font in which text was most recently drawn. If lockFlag is TRUE, SetFontLock makes the font unpurgeable (reading it into memory if it isn’t already there). If lockFlag is FALSE, it releases the memory occupied by the font (by calling the Resource Manager procedure ReleaseResource). Since fonts are normally purgeable, this procedure is useful for making a font temporarily unpurgeable. æKY SetFractEnable æFp Fonts.p æT PROCEDURE æD PROCEDURE SetFractEnable(fractEnable: BOOLEAN); æDT SetFractEnable(fractEnable); æRT 72 æRI SetFractEnable IV-32 routine V-180 æC Note: The extensions to the Font Manager described in the following paragraphs were originally documented in Inside Macintosh, Volume IV. As such, this information refers to the 128K ROMs and System file version 3.2 and later. SetFractEnable lets you enable or disable fractional character widths. If fractEnable is TRUE, fractional character widths are enabled; if it’s FALSE, the Font Manager uses integer widths. To ensure compatibility with existing applications, fractional character widths are disabled by default. SetFractEnable, which was not in the 128K ROM (but was available in the Pascal interfaces) has been added to both the Macintosh SE and Macintosh II ROMs. Assembly-language note: Assembly-language programmers should call SetFractEnable rather than change the value of the global variable FractEnable. æKY SetFScaleDisable æFp Fonts.p æT PROCEDURE æTN $A834 æD PROCEDURE SetFScaleDisable(fscaleDisable: BOOLEAN); æDT SetFScaleDisable(fscaleDisable); æRI SetFScaleDisable procedure IV-32 æC Note: The extensions to the Font Manager described in the following paragraphs were originally documented in Inside Macintosh, Volume IV. As such, this information refers to the 128K ROMs and System file version 3.2 and later. SetFScaleDisable lets you disable or enable font scaling. If fontScaleDisable is TRUE, font scaling is disabled and the Font Manager returns an unscaled font with more space around the characters; if it’s FALSE, the Font Manager scales fonts. To ensure compatibility with existing applications, the Font Manager defaults to scaling fonts. Assembly-language note: All programmers should use the SetFScaleDisable procedure to disable and enable font scaling. In particular, setting the global variable FScaleDisable is insufficient. æKY StyleTable æFp Fonts.p æT RECORD æC StyleTable = RECORD fontClass: INTEGER; offset: LONGINT; reserved: LONGINT; indexes: ARRAY [0..47] OF SignedByte; END; æKY systemFont,applFont,newYork,geneva,monaco,venice,london,athens,sanFran,toronto,cairo,losAngeles,times,helvetica,courier,symbol,taliesin æFp Fonts.p æC _______________________________________________________________________________ »FONT NUMBERS _______________________________________________________________________________ Note: The information on Font Numbers described in the following paragraphs was originally documented in Inside Macintosh, Volume I. The Font Manager includes the following font numbers for identifying system-defined fonts: CONST systemFont = 0; {system font} applFont = 1; {application font} newYork = 2; geneva = 3; monaco = 4; venice = 5; london = 6; athens = 7; sanFran = 8; toronto = 9; cairo = 11; losAngeles = 12; times = 20; helvetica = 21; courier = 22; symbol = 23; taliesin = 24; The system font is so called because it’s the font used by the system (for drawing menu titles and commands in menus, for example). The name of the system font is Chicago. The size of text drawn by the system in this font is fixed at 12 points (called the system font size). The application font is the font your application will use unless you specify otherwise. Unlike the system font, the application font isn’t a separate font, but is essentially a reference to another font—Geneva, by default. (The application font number is determined by a value that you can set in parameter RAM; see the Operating System Utilities chapter for more information.) Assembly-language note: You can get the application font number from the global variable ApFontID. æKY WidEntry æFp Fonts.p æT RECORD æC WidEntry = RECORD numWidths: INTEGER; {number of entries - 1} END; æKY WidthTable æFp Fonts.p æT PACKED RECORD æC WidthTable = PACKED RECORD tabData: ARRAY [1..256] OF Fixed; {character widths} tabFont: Handle; {font record used to build table} sExtra: LONGINT; {space extra used for table} style: LONGINT; {extra due to style} fID: INTEGER; {font family ID} fSize: INTEGER; {font size request} face: INTEGER; {style (face) request} device: INTEGER; {device requested} inNumer: Point; {scale factors requested} inDenom: Point; {scale factors requested} aFID: INTEGER; {actual font family ID for table} fHand: Handle; {family record used to build up table} usedFam: BOOLEAN; {used fixed point family widths} aFace: Byte; {actual face produced} vOutput: INTEGER; {vertical scale output value} hOutput: INTEGER; {horizontal scale output value} vFactor: INTEGER; {vertical scale output value} hFactor: INTEGER; {horizontal scale output value} aSize: INTEGER; {actual size of actual font used} tabSize: INTEGER; {total size of table} END; »Global Width Tables Note: The extensions to the Font Manager described in the following paragraphs were originally documented in Inside Macintosh, Volume IV. As such, this information refers to the 128K ROMs and System file version 3.2 and later. The Font Manager communicates fractional character widths to QuickDraw via a global width table, a data structure allocated in the system heap. A handle to the global width table is returned by the FontMetrics procedure. The format of the global width table is follows: TYPE WidthTable = RECORD tabData: ARRAY[1..256] OF Fixed; { character widths} tabFont: Handle; {font record used to build table} sExtra: LONGINT; {space extra used for table} style: LONGINT; {extra due to style} fID: INTEGER; {font family ID} fSize: INTEGER; {font size request} face: INTEGER; {style (face) request} device: INTEGER; {device requested} inNumer: Point; {numerators of scaling factors} inDenom: Point; {denominators of scaling factors} aFID: INTEGER; {actual font family ID for table} fHand: handle; {family record used to build table} usedFam: BOOLEAN; {used fixed-point family widths} aFace: Byte; {actual face produced} vOutput: INTEGER; {vertical factor for expanding } { characters} hOutput: INTEGER; {horizontal factor for expanding } { characters} vFactor: INTEGER; {not used} hFactor: INTEGER; {horizontal factor for increasing } { character widths} aSize: INTEGER; {actual size of actual font used} tabSize: INTEGER {total size of table} END; TabData is an array containing a character width for each of the 255 possible characters in a font, plus one long word for the font’s missing symbol. The widths are stored in the standard 32-bit fixed-point format. If a character is missing, its entry contains the width of the missing symbol. (For efficiency, the Font Manager will store up to 12 recently used global width tables.) InNumer and inDenom contain the vertical and horizontal scaling factors copied from the font input record. Scaling is effected in two ways: by expanding characters of the chosen font and by artificially increasing the widths of the chosen font in the width table. HOutput and vOutput give the factors by which characters are to be expanded horizontally and vertically. HFactor is the factor by which the widths of the chosen font, after stylistic variations, have been increased. (VFactor is not used.) Thus, multiplying hOutput and vOutput by hFactor and vFactor gives the true font scaling; the product of hOutput and an entry in the width table is that character’s true scaled width. HOutput,vOutput, hFactor, and vFactor are all 16-bit fixed-point numbers, with an integer part in the high-order byte and a fractional part in the low-order byte. If font scaling has been enabled, hFactor and vFactor both have a value of 1. In any case, hOutput, vOutput, hFactor, and vFactor are adjusted so that the values of hFactor and vFactor lie between 1 and 2, including 1. Assembly-language note: A handle to the global width table is contained in the global variable WidthTabHandle. A pointer to the table is contained in the global variable WidthPtr; it’s reliable immediately after a call to FMSwapFont but, like all pointers, may become invalid after a call to the Memory Manager. The global variable WidthListHand is a handle to a list of handles to up to 12 recently-used width tables. You can scan this list, looking for width tables that match the family number, size, and style of the font you wish to measure. If you reach a width handle that’s equal to –1, that width table is invalid, and you must make an FMSwapFont call to get a valid one. When you reach a handle that’s zero, you’ve reached the end of the list. You should not use the global width table when special international interface software is being used to accommodate non-Roman alphabets. You can recognize such software by looking at the global variable IntlSpec; if it’s greater than 0, special international software is installed. If your application uses non-Roman alphabets, write to Developer Technical Support Apple Computer, Inc. 20525 Mariani Avenue, M/S 75-3T Cupertino, CA 95014 for the latest version of the International Utilities Package, which will be extended to handle non-Roman alphabets. æKY Globals æKL ACount ANumber ApFontID ApplScratch AppParmHandle DABeeper DAStrings DefVCBPtr DlgFont DragPattern FCBSPtr FinderName FScaleDisable FSQHdr MBarEnable MBarHook MenuFlash MenuHook MenuList OldContent OldStructure PrintErr ROMFont0 SaveUpdate SaveVisRgn TheMenu ToExtFS ToolScratch VCBQHdr HiKeyLast KbdLast PCDeskPat Time ABusDCE ABusVars ADBBase AlarmState ApplLimit ApplZone ASCBase BootDrive BufPtr BufTgDate BufTgFBkNum BufTgFFlg BufTgFNum BusErrVct CaretTime ChunkyDepth ColLines CPUFlag CrsrAddr CrsrBase CrsrBusy CrsrCouple CrsrDevice CrsrNew CrsrObscure CrsrPin CrsrPtr CrsrRect CrsrRow CrsrSave CrsrScale CrsrState CrsrThresh CrsrVis CurActivate CurApName CurApRefNum CurDeactive CurDirStore CurJTOffset CurMap CurPageOption CurPitch CurrentA5 CurStackBase DefltStack DeskHook DeskPattern DeviceList DoubleTime DragHook DrvQHdr DSAlertRect DSAlertTab DSCtrAdj DSDrawProc DSErrCode DskErr DskVerify DSWndUpdate DTQFlags DTQueue DTskQHdr DTskQTail EjectNotify EndSRTPtr EventQueue EvtBufCnt ExpandMem ExtStsDT GetParam GhostWindow GrayRgn GZMoveHnd GZRootHnd GZRootPtr HeapEnd HiHeapMark HiliteMode HiliteRGB HpChk IAZNotify IconTLAddr IntFlag IntlSpec IWM JAllocCrsr JCrsrTask JDTInstall JFetch JGNEFilter JIODone JKybdTask JOpcodeProc JournalFlag JournalRef JSetCCrsr JStash JSwapMMU JVBLTask KbdType KbdVars Key1Trans Key2Trans KeyLast KeyMapLM KeyMVars KeypadMap KeyRepThresh KeyRepTime KeyThresh KeyTime LastTxGDevice LaunchFlag Lo3Bytes LoaderPBlock LoadTrap Lvl1DT Lvl2DT MainDevice MaskBC MaskHandle MaskPtr MBarHeight MBState MBTicks MemErr MemTop MickeyBytes MinStack MinusOne MMDefFlags MmInOK MMU32bit MMUFlags MMUFluff MMUTbl MMUTblSize MMUType MonkeyLives Mouse MouseMask MouseOffset MTemp NewCrsrJTbl NMIFlag OneOne PaintWhite PortAUse PortBUse PortList PWMBuf2 QDColors QDErrLM QDExist RAMBase RawMouse ResErr ResErrProc ResLoad ResReadOnly RestProc ResumeProc RGBBlack RGBWhite RndSeed ROM85 ROMBase ROMMapHndl RomMapInsert RowBits SaveSegHandle SCCASts SCCBSts SCCRd SCCWr ScrapCount ScrapEnd ScrapHandle ScrapInfo ScrapName ScrapSize ScrapState ScrapTag ScrapVars Scratch20 Scratch8 ScrDmpEnb ScrDmpType ScreenBytes ScreenRow ScrHRes ScrnBase ScrnVBLPtr ScrVRes SCSIBase SCSIDMA SCSIGlobals SCSIHsk SCSIPoll SdmBusErr SDMJmpTblPtr SdVolume SegHiEnable SerialVars SEVarBase SEvtEnb SFSaveDisk SInfoPtr SInitFlags SlotPrTbl SlotQDT SlotTICKS SlotVBLQ SoundActive SoundBase SoundDCE SoundLevel SoundPtr SoundVBL SPAlarm SPATalkA SPATalkB SPClikCaret SPConfig SPFont SPKbd SPMisc1 SPMisc2 SPPortA SPPortB SPPrint SPValid SPVolCtl SrcDevice SRsrcTblPtr StkLowPt SwitcherTPtr SysEvtBuf SysEvtMask SysMap SysMapHndl SysParam SysResName SysVersion SysZone TableSeed TagData TEDoText TERecal TEScrpHandle TEScrpLength TESysJust TEWdBreak TheCrsr TheGDevice TheZone Ticks TimeDBRA TimeLM TimeSCCDB TimeSCSIDB TmpResLoad TopMapHndl UnitNtryCnt UTableBase VBLQueue VertRRate VIA VIA2DT VideoInfoOK VidMode VidType WarmStart WindowList WMgrCPort WMgrPort WordRedraw WWExist æKY ACount æFp Globals æC ACount = $A9A [GLOBAL VAR] Stage number (0 through 3) of last alert (word) æKY ANumber æFp Globals æC ANumber = $A98 [GLOBAL VAR] Resource ID of last alert (word) æKY ApFontID æFp Globals æC ApFontID = $984 [GLOBAL VAR] Font number of application font (word) æKY ApplScratch æFp Globals æC ApplScratch = $A78 [GLOBAL VAR] 12-byte scratch area reserved for use by applications æKY AppParmHandle æFp Globals æC AppParmHandle = $AEC [GLOBAL VAR] Handle to Finder information æKY DABeeper æFp Globals æC DABeeper = $A9C [GLOBAL VAR] Address of current sound procedure æKY DAStrings æFp Globals æC DAStrings = $AA0 [GLOBAL VAR] Handles to ParamText strings (16 bytes) æKY DefVCBPtr æFp Globals æC DefVCBPtr = $352 [GLOBAL VAR] Pointer to default volume control block æKY DlgFont æFp Globals æC DlgFont = $AFA [GLOBAL VAR] Font number for dialogs and alerts (word) æKY DragPattern æFp Globals æC DragPattern = $A34 [GLOBAL VAR] Pattern of dragged region's outline (8 bytes) æKY FCBSPtr æFp Globals æC FCBSPtr = $34E [GLOBAL VAR] Pointer to file-control-block buffer æKY FinderName æFp Globals æC FinderName = $2E0 [GLOBAL VAR] Name of the Finder (length byte followed by up to 15 characters) æKY FScaleDisable æFp Globals æC FScaleDisable = $A63 [GLOBAL VAR] Nonzero to disable font scaling (byte) æKY FSQHdr æFp Globals æC FSQHdr = $360 [GLOBAL VAR] File I/O queue header (10 bytes) æKY MBarEnable æFp Globals æC MBarEnable = $A20 [GLOBAL VAR] Unique menu ID for active desk accessory, when menu bar belongs to the accessory (word) æKY MBarHook æFp Globals æC MBarHook = $A2C [GLOBAL VAR] Address of routine called by MenuSelect before menu is drawn æKY MenuFlash æFp Globals æC MenuFlash = $A24 [GLOBAL VAR] Count for duration of menu item blinking (word) æKY MenuHook æFp Globals æC MenuHook = $A30 [GLOBAL VAR] Address of routine called during MenuSelect æKY MenuList æFp Globals æC MenuList = $A1C [GLOBAL VAR] Handle to current menu list æKY OldContent æFp Globals æC OldContent = $9EA [GLOBAL VAR] Handle to saved content region æKY OldStructure æFp Globals æC OldStructure = $9E6 [GLOBAL VAR] Handle to saved structure region æKY PrintErr æFp Globals æC PrintErr = $944 [GLOBAL VAR] Result code from last Printing Manager routine (word) æKY ROMFont0 æFp Globals æC ROMFont0 = $980 [GLOBAL VAR] Handle to font record for system font æKY SaveUpdate æFp Globals æC SaveUpdate = $9DA [GLOBAL VAR] Flag for whether to generate update events (word) æKY SaveVisRgn æFp Globals æC SaveVisRgn = $9F2 [GLOBAL VAR] Handle to saved visRgn æKY TheMenu æFp Globals æC TheMenu = $A26 [GLOBAL VAR] Menu ID of currently highlighted menu (word) æKY ToExtFS æFp Globals æC ToExtFS = $3F2 [GLOBAL VAR] Pointer to external file system æKY ToolScratch æFp Globals æC ToolScratch = $9CE [GLOBAL VAR] 8-byte scratch area æKY VCBQHdr æFp Globals æC VCBQHdr = $356 [GLOBAL VAR] Volume-control-block queue header (10 bytes) æKY Graf3D.p æKL Clip3D GetPort3D Identity InitGrf3d Line2D Line3D LineTo2D LineTo3D LookAt Move2D Move3D MoveTo2D MoveTo3D Open3DPort Pitch Roll Scale SetPort3D SetPt2D SetPt3D Skew Transform Translate ViewAngle ViewPort Yaw radConst XfMatrix æKY Port3D æFp Graf3D.p æT RECORD æC Port3D = RECORD grPort: GrafPtr; viewRect: Rect; xLeft: Fixed; yTop: Fixed; xRight: Fixed; yBottom: Fixed; pen: Point3D; penPrime: Point3D; eye: Point3D; hSize: Fixed; vSize: Fixed; hCenter: Fixed; vCenter: Fixed; xCotan: Fixed; yCotan: Fixed; ident: BOOLEAN; xForm: XfMatrix; END; æKY Port3DPtr æFp Graf3D.p æT TYPE æC Port3DPtr = ^Port3D; Port3D = RECORD grPort: GrafPtr; viewRect: Rect; xLeft: Fixed; yTop: Fixed; xRight: Fixed; yBottom: Fixed; pen: Point3D; penPrime: Point3D; eye: Point3D; hSize: Fixed; vSize: Fixed; hCenter: Fixed; vCenter: Fixed; xCotan: Fixed; yCotan: Fixed; ident: BOOLEAN; xForm: XfMatrix; END; æKY Clip3D æFp Graf3D.p æT FUNCTION æD FUNCTION Clip3D(src1: Point3D;src2: Point3D;VAR dst1: Point;VAR dst2: Point): INTEGER; æDT myVariable := Clip3D(src1,src2,dst1,dst2); æKY GetPort3D æFp Graf3D.p æT PROCEDURE æD PROCEDURE GetPort3D(VAR port: Port3DPtr); æDT GetPort3D(port); æC GetPort returns a pointer to the current grafPort. If you have a program that draws into more than one grafPort, it's extremely useful to have each procedure save the current grafPort (with GetPort), set its own grafPort, do drawing or calculations, and then restore the previous grafPort (with SetPort). The pointer to the current grafPort is also available through the global pointer thePort, but you may prefer to use GetPort for better readability of your program text. For example, a procedure could do a GetPort (savePort) before setting its own grafPort and a SetPort (savePort) afterwards to restore the previous port. æKY Identity æFp Graf3D.p æT PROCEDURE æD PROCEDURE Identity; æDT Identity; æKY InitGrf3d æFp Graf3D.p æT PROCEDURE æD PROCEDURE InitGrf3d(port: Port3DPtr); æDT InitGrf3d(port); æKY Line2D æFp Graf3D.p æT PROCEDURE æD PROCEDURE Line2D(dx: Fixed;dy: Fixed); æDT Line2D(dx,dy); æKY Line3D æFp Graf3D.p æT PROCEDURE æD PROCEDURE Line3D(dx: Fixed;dy: Fixed;dz: Fixed); æDT Line3D(dx,dy,dz); æKY LineTo2D æFp Graf3D.p æT PROCEDURE æD PROCEDURE LineTo2D(x: Fixed;y: Fixed); æDT LineTo2D(x,y); æC This procedure draws a line to the location that is a distance of dh horizontally and dv vertically from the current pen location; it calls LineTo(h+dh,v+dv), where (h,v) is the current location. The positive directions are to the right and down. The pen location becomes the coordinates of the end of the line after the line is drawn. See the general discussion of drawing. If a region or polygon is open and being formed, its outline is infinitely thin and is not affected by the pnSize, pnMode, or pnPat. (See OpenRgn and OpenPoly.) æKY LineTo3D æFp Graf3D.p æT PROCEDURE æD PROCEDURE LineTo3D(x: Fixed;y: Fixed;z: Fixed); æDT LineTo3D(x,y,z); æKY LookAt æFp Graf3D.p æT PROCEDURE æD PROCEDURE LookAt(left: Fixed;top: Fixed;right: Fixed;bottom: Fixed); æDT LookAt(left,top,right,bottom); æKY Move2D æFp Graf3D.p æT PROCEDURE æD PROCEDURE Move2D(dx: Fixed;dy: Fixed); æDT Move2D(dx,dy); æKY Move3D æFp Graf3D.p æT PROCEDURE æD PROCEDURE Move3D(dx: Fixed;dy: Fixed;dz: Fixed); æDT Move3D(dx,dy,dz); æKY MoveTo2D æFp Graf3D.p æT PROCEDURE æD PROCEDURE MoveTo2D(x: Fixed;y: Fixed); æDT MoveTo2D(x,y); æC MoveTo moves the pen to location (h,v) in the local coordinates of the current grafPort. No drawing is performed. æKY MoveTo3D æFp Graf3D.p æT PROCEDURE æD PROCEDURE MoveTo3D(x: Fixed;y: Fixed;z: Fixed); æDT MoveTo3D(x,y,z); æKY Open3DPort æFp Graf3D.p æT PROCEDURE æD PROCEDURE Open3DPort(port: Port3DPtr); æDT Open3DPort(port); æKY Pitch æFp Graf3D.p æT PROCEDURE æD PROCEDURE Pitch(xAngle: Fixed); æDT Pitch(xAngle); æKY Point2D æFp Graf3D.p æT RECORD æC Point2D = RECORD x: Fixed; y: Fixed; END; æKY Point3D æFp Graf3D.p æT RECORD æC Point3D = RECORD x: Fixed; y: Fixed; z: Fixed; END; æKY radConst æFp Graf3D.p æC radConst = 3754936; æKY Roll æFp Graf3D.p æT PROCEDURE æD PROCEDURE Roll(zAngle: Fixed); æDT Roll(zAngle); æKY Scale æFp Graf3D.p æT PROCEDURE æD PROCEDURE Scale(xFactor: Fixed;yFactor: Fixed;zFactor: Fixed); æDT Scale(xFactor,yFactor,zFactor); æKY SetPort3D æFp Graf3D.p æT PROCEDURE æD PROCEDURE SetPort3D(port: Port3DPtr); æDT SetPort3D(port); æC SetPort sets the grafPort indicated by gp to be the current port. The global pointer thePort always points to the current port. All QuickDraw drawing routines affect the bitMap thePort^.portBits and use the local coordinate system of thePort^. Note that OpenPort and InitPort do a SetPort to the given port. Warning: Never do a SetPort to a port that has not been opened with OpenPort. Each port possesses its own pen and text characteristics which remain unchanged when the port is not selected as the current port. æKY SetPt2D æFp Graf3D.p æT PROCEDURE æD PROCEDURE SetPt2D(VAR pt2D: Point2D;x: Fixed;y: Fixed); æDT SetPt2D(pt2D,x,y); æKY SetPt3D æFp Graf3D.p æT PROCEDURE æD PROCEDURE SetPt3D(VAR pt3D: Point3D;x: Fixed;y: Fixed;z: Fixed); æDT SetPt3D(pt3D,x,y,z); æC SetPt assigns two integer coordinates to a variable of type Point. æKY Skew æFp Graf3D.p æT PROCEDURE æD PROCEDURE Skew(zAngle: Fixed); æDT Skew(zAngle); æKY Transform æFp Graf3D.p æT PROCEDURE æD PROCEDURE Transform(src: Point3D;VAR dst: Point3D); æDT Transform(src,dst); æKY Translate æFp Graf3D.p æT PROCEDURE æD PROCEDURE Translate(dx: Fixed;dy: Fixed;dz: Fixed); æDT Translate(dx,dy,dz); æKY ViewAngle æFp Graf3D.p æT PROCEDURE æD PROCEDURE ViewAngle(angle: Fixed); æDT ViewAngle(angle); æKY ViewPort æFp Graf3D.p æT PROCEDURE æD PROCEDURE ViewPort(r: Rect); æDT ViewPort(r); æKY XfMatrix æFp Graf3D.p æT TYPE æC XfMatrix = ARRAY [0..3, 0..3] OF Fixed; æKY Yaw æFp Graf3D.p æT PROCEDURE æD PROCEDURE Yaw(yAngle: Fixed); æDT Yaw(yAngle); æKY HyperXCmd.p æKL BoolToStr EvalExpr ExtToStr GetFieldByID GetFieldByName GetFieldByNum GetGlobal LongToStr NumToHex NumToStr PasToZero ReturnToPas ScanToReturn ScanToZero SendCardMessage SendHCMessage SetFieldByID SetFieldByName SetFieldByNum SetGlobal StringEqual StringLength StringMatch StrToBool StrToExt StrToLong StrToNum ZeroBytes ZeroToPas XCmdBlock XCmdPtr xreqBoolToStr xreqEvalExpr xreqExtToStr xreqGetFieldByID xreqGetFieldByName xreqGetFieldByNum xreqGetGlobal xreqLongToStr xreqNumToHex xreqNumToStr xreqPasToZero xreqReturnToPas xreqScanToReturn xreqScanToZero xreqSendCardMessage xreqSendHCMessage xreqSetFieldByID xreqSetFieldByName xreqSetFieldByNum xreqSetGlobal xreqStringEqual xreqStringLength xreqStringMatch xreqStrToBool xreqStrToExt xreqStrToLong xreqStrToNum xreqZeroBytes xreqZeroToPas xresFail xresNotImp xresSucc æKY XCmdBlock æFp HyperXCmd.p æT RECORD æC XCmdBlock = RECORD paramCount: INTEGER; params: ARRAY [1..16] OF Handle; returnValue: Handle; passFlag: BOOLEAN; entryPoint: ProcPtr; {to call back to HyperCard} request: INTEGER; result: INTEGER; inArgs: ARRAY [1..8] OF LONGINT; outArgs: ARRAY [1..4] OF LONGINT; END; æKY XCmdPtr æFp HyperXCmd.p æT TYPE æC XCmdPtr = ^XCmdBlock; XCmdBlock = RECORD paramCount: INTEGER; params: ARRAY [1..16] OF Handle; returnValue: Handle; passFlag: BOOLEAN; entryPoint: ProcPtr; {to call back to HyperCard} request: INTEGER; result: INTEGER; inArgs: ARRAY [1..8] OF LONGINT; outArgs: ARRAY [1..4] OF LONGINT; END; æKY BoolToStr æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE BoolToStr(paramPtr: XCmdPtr;bool: BOOLEAN;VAR str: Str255); æDT BoolToStr(paramPtr,bool,str); æKY EvalExpr æFp HyperXCmd.p æT FUNCTION æD FUNCTION EvalExpr(paramPtr: XCmdPtr;expr: Str255): Handle; æDT myVariable := EvalExpr(paramPtr,expr); æKY ExtToStr æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE ExtToStr(paramPtr: XCmdPtr;num: Extended;VAR str: Str255); æDT ExtToStr(paramPtr,num,str); æKY GetFieldByID æFp HyperXCmd.p æT FUNCTION æD FUNCTION GetFieldByID(paramPtr: XCmdPtr;cardFieldFlag: BOOLEAN;fieldID: INTEGER): Handle; æDT myVariable := GetFieldByID(paramPtr,cardFieldFlag,fieldID); æKY GetFieldByName æFp HyperXCmd.p æT FUNCTION æD FUNCTION GetFieldByName(paramPtr: XCmdPtr;cardFieldFlag: BOOLEAN;fieldName: Str255): Handle; æDT myVariable := GetFieldByName(paramPtr,cardFieldFlag,fieldName); æKY GetFieldByNum æFp HyperXCmd.p æT FUNCTION æD FUNCTION GetFieldByNum(paramPtr: XCmdPtr;cardFieldFlag: BOOLEAN;fieldNum: INTEGER): Handle; æDT myVariable := GetFieldByNum(paramPtr,cardFieldFlag,fieldNum); æKY GetGlobal æFp HyperXCmd.p æT FUNCTION æD FUNCTION GetGlobal(paramPtr: XCmdPtr;globName: Str255): Handle; æDT myVariable := GetGlobal(paramPtr,globName); æKY LongToStr æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE LongToStr(paramPtr: XCmdPtr;posNum: LONGINT;VAR str: Str255); æDT LongToStr(paramPtr,posNum,str); æKY NumToHex æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE NumToHex(paramPtr: XCmdPtr;num: LONGINT;nDigits: INTEGER;VAR str: Str255); æDT NumToHex(paramPtr,num,nDigits,str); æKY NumToStr æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE NumToStr(paramPtr: XCmdPtr;num: LONGINT;VAR str: Str255); æDT NumToStr(paramPtr,num,str); æKY PasToZero æFp HyperXCmd.p æT FUNCTION æD FUNCTION PasToZero(paramPtr: XCmdPtr;str: Str255): Handle; æDT myVariable := PasToZero(paramPtr,str); æKY ReturnToPas æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE ReturnToPas(paramPtr: XCmdPtr;zeroStr: UNIV Ptr;VAR pasStr: Str255); æDT ReturnToPas(paramPtr,zeroStr,pasStr); æKY ScanToReturn æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE ScanToReturn(paramPtr: XCmdPtr;VAR scanPtr: Ptr); æDT ScanToReturn(paramPtr,scanPtr); æKY ScanToZero æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE ScanToZero(paramPtr: XCmdPtr;VAR scanPtr: Ptr); æDT ScanToZero(paramPtr,scanPtr); æKY SendCardMessage æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE SendCardMessage(paramPtr: XCmdPtr;msg: Str255); æDT SendCardMessage(paramPtr,msg); æKY SendHCMessage æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE SendHCMessage(paramPtr: XCmdPtr;msg: Str255); æDT SendHCMessage(paramPtr,msg); æKY SetFieldByID æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE SetFieldByID(paramPtr: XCmdPtr;cardFieldFlag: BOOLEAN;fieldID: INTEGER; fieldVal: Handle); æDT SetFieldByID(paramPtr,cardFieldFlag,fieldID,fieldVal); æKY SetFieldByName æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE SetFieldByName(paramPtr: XCmdPtr;cardFieldFlag: BOOLEAN;fieldName: Str255; fieldVal: Handle); æDT SetFieldByName(paramPtr,cardFieldFlag,fieldName,fieldVal); æKY SetFieldByNum æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE SetFieldByNum(paramPtr: XCmdPtr;cardFieldFlag: BOOLEAN;fieldNum: INTEGER; fieldVal: Handle); æDT SetFieldByNum(paramPtr,cardFieldFlag,fieldNum,fieldVal); æKY SetGlobal æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE SetGlobal(paramPtr: XCmdPtr;globName: Str255;globValue: Handle); æDT SetGlobal(paramPtr,globName,globValue); æKY StringEqual æFp HyperXCmd.p æT FUNCTION æD FUNCTION StringEqual(paramPtr: XCmdPtr;str1: Str255;str2: Str255): BOOLEAN; æDT myVariable := StringEqual(paramPtr,str1,str2); æKY StringLength æFp HyperXCmd.p æT FUNCTION æD FUNCTION StringLength(paramPtr: XCmdPtr;strPtr: UNIV Ptr): LONGINT; æDT myVariable := StringLength(paramPtr,strPtr); æKY StringMatch æFp HyperXCmd.p æT FUNCTION æD FUNCTION StringMatch(paramPtr: XCmdPtr;pattern: Str255;target: Ptr): Ptr; æDT myVariable := StringMatch(paramPtr,pattern,target); æKY StrToBool æFp HyperXCmd.p æT FUNCTION æD FUNCTION StrToBool(paramPtr: XCmdPtr;str: Str255): BOOLEAN; æDT myVariable := StrToBool(paramPtr,str); æKY StrToExt æFp HyperXCmd.p æT FUNCTION æD FUNCTION StrToExt(paramPtr: XCmdPtr;str: Str255): Extended; æDT myVariable := StrToExt(paramPtr,str); æKY StrToLong æFp HyperXCmd.p æT FUNCTION æD FUNCTION StrToLong(paramPtr: XCmdPtr;str: Str255): LONGINT; æDT myVariable := StrToLong(paramPtr,str); æKY StrToNum æFp HyperXCmd.p æT FUNCTION æD FUNCTION StrToNum(paramPtr: XCmdPtr;str: Str255): LONGINT; æDT myVariable := StrToNum(paramPtr,str); æKY xreqBoolToStr æFp HyperXCmd.p æC xreqBoolToStr = 16; æKY xreqEvalExpr æFp HyperXCmd.p æC xreqEvalExpr = 2; æKY xreqExtToStr æFp HyperXCmd.p æC xreqExtToStr = 17; æKY xreqGetFieldByID æFp HyperXCmd.p æC xreqGetFieldByID = 22; æKY xreqGetFieldByName æFp HyperXCmd.p æC xreqGetFieldByName = 20; æKY xreqGetFieldByNum æFp HyperXCmd.p æC xreqGetFieldByNum = 21; æKY xreqGetGlobal æFp HyperXCmd.p æC xreqGetGlobal = 18; æKY xreqLongToStr æFp HyperXCmd.p æC xreqLongToStr = 13; æKY xreqNumToHex æFp HyperXCmd.p æC xreqNumToHex = 15; æKY xreqNumToStr æFp HyperXCmd.p æC xreqNumToStr = 14; æKY xreqPasToZero æFp HyperXCmd.p æC xreqPasToZero = 7; æKY xreqReturnToPas æFp HyperXCmd.p æC xreqReturnToPas = 27; æKY xreqScanToReturn æFp HyperXCmd.p æC xreqScanToReturn = 28; æKY xreqScanToZero æFp HyperXCmd.p æC xreqScanToZero = 39; { Yes, really 39!} æKY xreqSendCardMessage æFp HyperXCmd.p æC xreqSendCardMessage = 1; æKY xreqSendHCMessage æFp HyperXCmd.p æC xreqSendHCMessage = 5; æKY xreqSetFieldByID æFp HyperXCmd.p æC xreqSetFieldByID = 25; æKY xreqSetFieldByName æFp HyperXCmd.p æC xreqSetFieldByName = 23; æKY xreqSetFieldByNum æFp HyperXCmd.p æC xreqSetFieldByNum = 24; æKY xreqSetGlobal æFp HyperXCmd.p æC xreqSetGlobal = 19; æKY xreqStringEqual æFp HyperXCmd.p æC xreqStringEqual = 26; æKY xreqStringLength æFp HyperXCmd.p æC xreqStringLength = 3; æKY xreqStringMatch æFp HyperXCmd.p æC xreqStringMatch = 4; æKY xreqStrToBool æFp HyperXCmd.p æC xreqStrToBool = 11; æKY xreqStrToExt æFp HyperXCmd.p æC xreqStrToExt = 12; æKY xreqStrToLong æFp HyperXCmd.p æC xreqStrToLong = 9; æKY xreqStrToNum æFp HyperXCmd.p æC xreqStrToNum = 10; æKY xreqZeroBytes æFp HyperXCmd.p æC xreqZeroBytes = 6; æKY xreqZeroToPas æFp HyperXCmd.p æC xreqZeroToPas = 8; æKY xresFail æFp HyperXCmd.p æC xresFail = 1; æKY xresNotImp æFp HyperXCmd.p æC xresNotImp = 2; æKY xresSucc æFp HyperXCmd.p æC xresSucc = 0; æKY ZeroBytes æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE ZeroBytes(paramPtr: XCmdPtr;dstPtr: Ptr;longCount: LONGINT); æDT ZeroBytes(paramPtr,dstPtr,longCount); æKY ZeroToPas æFp HyperXCmd.p æT PROCEDURE æD PROCEDURE ZeroToPas(paramPtr: XCmdPtr;zeroStr: UNIV Ptr;VAR pasStr: Str255); æDT ZeroToPas(paramPtr,zeroStr,pasStr); æKY Lists.p æKL LActivate LAddColumn LAddRow LAddToCell LAutoScroll LCellSize LClick LClrCell LDelColumn LDelRow LDispose LDoDraw LDraw LFind LGetCell LGetSelect LLastClick LNew LNextCell LRect LScroll LSearch LSetCell LSetSelect LSize LUpdate Cell DataArray DataHandle DataPtr lCloseMsg lDoHAutoscroll lDoVAutoscroll lDrawMsg lExtendDrag lHiliteMsg lInitMsg ListHandle ListPtr ListRec lNoDisjoint lNoExtend lNoNilHilite lNoRect lOnlyOne lUseSense Point æKY ListRec,ListPtr,ListHandle æFp Lists.p æT TYPE æC ListPtr = ^ListRec; ListHandle = ^ListPtr; ListRec = RECORD rView: Rect; port: GrafPtr; indent: Point; cellSize: Point; visible: Rect; vScroll: ControlHandle; hScroll: ControlHandle; selFlags: SignedByte; lActive: BOOLEAN; lReserved: SignedByte; listFlags: SignedByte; clikTime: LONGINT; clikLoc: Point; mouseLoc: Point; lClikLoop: ProcPtr; lastClick: Cell; refCon: LONGINT; listDefProc: Handle; userHandle: Handle; dataBounds: Rect; cells: DataHandle; maxIndex: INTEGER; cellArray: ARRAY [1..1] OF INTEGER; END; »The List Record Data Structure The exact data structure of a list record is as follows: TYPE Cell = Point; DataArray = PACKED ARRAY [0..32000] OF CHAR; DataPtr = ^DataArray; DataHandle = ^DataPtr; ListRec = RECORD rView: Rect; {list's display rectangle} port: GrafPtr; {list's grafPort} indent: Point; {indent distance} cellSize: Point; {cell size} visible: Rect; {boundary of visible cells} vScroll: ControlHandle; {vertical scroll bar} hScroll: ControlHandle; {horizontal scroll bar} selFlags: SignedByte; {selection flags} lActive: BOOLEAN; {TRUE if active} lReserved: SignedByte; {reserved} listFlags: SignedByte; {automatic scrolling flags} clikTime: LONGINT; {time of last click} clikLoc: Point; {position of last click} mouseLoc: Point; {current mouse location} lClikLoop: Ptr; {routine for LClick} lastClick: Cell; {last cell clicked} refCon: LONGINT; {list's reference value} listDefProc: Handle; {list definition procedure} userHandle: Handle; {additional storage} dataBounds: Rect; {boundary of cells allocated} cells: DataHandle; {cell data} maxIndex: INTEGER; {used internally} cellArray: ARRAY [1..1] OF INTEGER {offsets to data} END; ListPtr = ^ListRec; ListHandle = ^ListPtr; RView is the rectangle, given in the local coordinates of the grafPort, in which the list is displayed. Room for scroll bars is not included in this rectangle. If the list has scroll bars and is to fill the entire window, rView should be 15 points smaller in each dimension than the grafPort. Port is the grafPort used by the list; it’s set to the port of the window specified when the list is created. Indent is the distance in pixels that the list definition procedure should indent from the topLeft of the cell when drawing the contents. The default value for indent is 0, but it can be set by the list definition procedure. CellSize is the size of a cell in pixels. If it’s not specified when the list is created, a default cell size is set. CellSize.v is set to the ascent plus descent plus leading of the port’s font, and cellSize.h is set to (rView.right – rView.left) DIV (dataBounds.right – dataBounds.left) A cell is a box in which a list element is displayed. Cells are identified by their column and row numbers. In Figure 1, for instance, the highlighted cell is in column 1, row 2. Cells are declared as points, using the Point data type simply as a way of specifying the column and row number of a cell. Similarly, visible and dataBounds use the Rect data type to specify a rectangular set of cells as two diagonally opposite cell coordinates (rather than two diagonally opposite points in the local coordinates of a grafPort). DataBounds is the boundary of the cells currently allocated, specified by row and column. The list in Figure 1 (assuming the entire list is visible) has seventeen rows and five columns of cells. DataBounds for this list can be represented, using the QuickDraw rectangle notation (left,top)(right,bottom), as (0,0)(5,17). Notice that the column and row specified for the bottom right of dataBounds are 1 greater in each dimension than the column and row number of the bottom right cell. Thus, you can test to see if a cell is a valid cell within the boundary of a list using the statement: IF PtInRect(c,myList^^.dataBounds) THEN... The visible rectangle reflects which cells are currently within the visible part of the list; it’s calculated by the List Manager according to the values you specify for rView, dataBounds, and cellSize when you create the list. (Visible.topLeft is the row and column of the top left visible cell; visible.botRight is 1 greater in both dimensions than the row and column of the bottom right visible cell.) For example, if only four cells—row 2, column 0; row 2, column 1; row 3, column 0; and row 3, column 1—are visible, the visible rectangle is (0,2)(2,4). You can test to see if a cell is visible using the statement: IF PtInRect(c,myList^^.visible) THEN... •••Refer to Figure 1.••• Figure 1–A Sample List SelFlags contains selection flags for the List Manager. It’s initialized to 0; with this setting, the List Manager selects cells according to the Macintosh User Interface Guidelines. The meaning of these flags is explained below in the section “Cell Selection Algorithm”. The listFlags field contains automatic scrolling flags; the List Manager sets these flags automatically when you specify scroll bars. There are predefined constants that let you set or test the status of the corresponding bits: CONST lDoVAutoScroll = 2; {set to allow automatic vertical scrolling} lDoHAutoScroll = 1; {set to allow automatic horizontal scrolling} ClikLoc is the position of the last mouse click in local coordinates; you can use it in the list definition procedure to get the position within the cell. LClikLoop is a pointer to the routine to be called during the LClick function, as described later. LastClick contains the cell coordinates of the last cell clicked in. RefCon is the list’s reference value field, which the application may store into and access for any purpose. In addition, the application may use the field userHandle to store a handle to an additional storage area. CellArray contains offsets to the cell data. For each list element, this includes the bit indicating whether the cell is selected or not. »The LClikLoop Field The lClikLoop field of a list record lets you specify a routine that will be called repeatedly (by the LClick function, described below) as long as the mouse button is held down within the rView rectangle or its scroll bars. Note: The LClick function performs automatic scrolling if the mouse is dragged outside the visible rectangle, so there’s no need to write a list click loop routine to do automatic scrolling. The list click loop routine has no parameters and returns a Boolean value. You could declare a list click loop routine named MyClikLoop like this: FUNCTION MyClikLoop : BOOLEAN; The function should return TRUE. You must put a pointer to your list click loop routine in the lClikLoop field of the list record so that the List Manager will call your routine. Warning: Returning FALSE from your list click loop routine tells the LClick function that the mouse button has been released, which aborts LClick. Assembly-language note: Your routine should set register D0 to 1; returning 0 in register D0 aborts LClick. For your convenience, register D5 contains the current mouse location. æKY Cell,Point æFp Lists.p æT TYPE æC Cell = Point; Point = RECORD CASE INTEGER OF 1: (v: INTEGER; {vertical coordinate} h: INTEGER); {horizontal coordinate} 2: (vh: ARRAY[VHSelect] OF INTEGER); END; æKY DataHandle,DataPtr,DataArray æFp Lists.p æT TYPE æC DataPtr = ^DataArray; DataHandle = ^DataPtr; DataArray = PACKED ARRAY [0..32000] OF CHAR; æKY LActivate æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LActivate(act: BOOLEAN;lHandle: ListHandle); æDT LActivate(act,lHandle); æRI LActivate procedure IV-276 æC Call LActivate to activate or deactivate the list specified by lHandle (in response to an activate event in the window containing the list). The act parameter should be set to TRUE to activate the list, or FALSE to deactivate the list. LActivate highlights or unhighlights the selections, and shows or hides the scroll bars (but not the size box, if any). Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LAddColumn æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LAddColumn(count: INTEGER;colNum: INTEGER;lHandle: ListHandle): INTEGER; æDT myVariable := LAddColumn(count,colNum,lHandle); æRI LAddColumn function IV-271 æC LAddColumn inserts into the given list the number of columns specified by the count parameter, starting at the column specified by colNum. Column numbers that are greater than or equal to colNum are increased by count. If colNum is not within dataBounds, new last columns are added. The number of the first added column is returned and dataBounds.right is increased by count. All cells added are empty. If there are no cells (because dataBounds.top = dataBounds.bottom), no cells are added, but dataBounds is still extended. If drawing is on and the added columns (which are empty) are visible, the list and its scroll bars are updated. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LAddRow æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LAddRow(count: INTEGER;rowNum: INTEGER;lHandle: ListHandle): INTEGER; æDT myVariable := LAddRow(count,rowNum,lHandle); æRI LAddRow function IV-271 æC LAddRow inserts the number of rows specified by the count parameter, starting at the row specified by rowNum. Row numbers that are greater than or equal to rowNum are increased by count. If rowNum is not within dataBounds, new last rows are added. The number of the first added row is returned, and dataBounds.bottom is increased by count. All cells added are empty. If there are no cells (because dataBounds.left = dataBounds.right), no cells are added, but dataBounds is still extended. If drawing is on and the added rows (which are empty) are visible, the list and its scroll bars are updated. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LAddToCell æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LAddToCell(dataPtr: Ptr;dataLen: INTEGER;theCell: Cell;lHandle: ListHandle); æDT LAddToCell(dataPtr,dataLen,theCell,lHandle); æRI LAddToCell procedure IV-272 æC LAddToCell appends the data pointed to by dataPtr and of length dataLen to the cell specified by theCell in lHandle. If drawing is off, you must turn drawing on and call LDraw (or LUpdate) to display the cell’s new value. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LAutoScroll æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LAutoScroll(lHandle: ListHandle); æDT LAutoScroll(lHandle); æRI LAutoScroll procedure IV-275 æC For the given list, LAutoScroll scrolls the list until the first selected cell is visible. It automatically places the first selected cell in the top left corner of the visible rectangle. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LCellSize æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LCellSize(cSize: Point;lHandle: ListHandle); æDT LCellSize(cSize,lHandle); æRI LCellSize procedure IV-273 æC LCellSize sets the cellSize field in the list record to cSize and updates the visible rectangle to contain cells of this size. This command should be used only before any cells have been drawn. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LClick æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LClick(pt: Point;modifiers: INTEGER;lHandle: ListHandle): BOOLEAN; æDT myVariable := LClick(pt,modifiers,lHandle); æRI LClick function IV-273 æC Call LClick when there is a mouse-down event in the destination rectangle or its scroll bars. Pt is the mouse location in local coordinates. Modifiers is the modifiers word from the event record. LHandle is the list to be tracked. The result is TRUE if a double-click occurred (and the two clicks took place within the same cell). LClick keeps control until the mouse is released; each time through its inner loop, it calls the routine whose pointer is in the lClikLoop field of the list record. If the mouse is in the visible rectangle, cells are selected according to the state of the modifiers and the selection flags. If the mouse was in the cells but is dragged outside the list’s rectangle, the list is auto-scrolled. If the mouse was in a control, the control’s definition procedure is called to track the mouse. To discover which cell was clicked in, use the LLastClick function. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LClrCell æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LClrCell(theCell: Cell;lHandle: ListHandle); æDT LClrCell(theCell,lHandle); æRI LClrCell procedure IV-272 æC LClrCell clears the contents of the specified cell (by setting the length to 0). If theCell is not a valid cell, nothing is done. If drawing is off, you must turn drawing on and call LDraw to display the cell’s new value (or simply call the Window Manager procedure InvalRect). Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LDelColumn æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LDelColumn(count: INTEGER;colNum: INTEGER;lHandle: ListHandle); æDT LDelColumn(count,colNum,lHandle); æRI LDelColumn procedure IV-271 æC LDelColumn deletes the number of columns specified by the count parameter, starting with the column specified by colNum. Column numbers that are greater than colNum are decreased by count. If colNum is not within dataBounds, nothing is done. DataBounds.right is decreased by count. If drawing is on and the deleted columns were visible, the list and its scroll bars are updated. If count is 0, or colNum = dataBounds.left AND count > = dataBounds.right – dataBounds.left all the data in the list is quickly deleted, dataBounds.right is set to dataBounds.left, and the number of rows is left unchanged. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LDelRow æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LDelRow(count: INTEGER;rowNum: INTEGER;lHandle: ListHandle); æDT LDelRow(count,rowNum,lHandle); æRI LDelRow procedure IV-272 æC LDelRow deletes the number of rows specified by the count parameter, starting with the row specified by rowNum. Row numbers that are greater than rowNum are decreased by count. If rowNum is not within dataBounds, nothing is done. DataBounds.bottom is decreased by count. If drawing is on and the deleted rows were visible, the list and its scroll bars are updated. If count is 0, or rowNum = dataBounds.top AND count > = dataBounds.bottom – dataBounds.top all the data in the list is quickly deleted, dataBounds.bottom is set to dataBounds.top, and the number of columns is left unchanged. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LDispose æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LDispose(lHandle: ListHandle); æDT LDispose(lHandle); æRI LDispose procedure IV-271 æC Call LDispose when you are through using a list. It issues a close call to the list definition procedure, and calls the Memory Manager procedure DisposHandle for the data handle, the Control Manager procedure DisposeControl for both scroll bars (if they’re there), and DisposHandle for the list record. Note: Calling LDispose is much faster than deleting one row at a time. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LDoDraw æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LDoDraw(drawIt: BOOLEAN;lHandle: ListHandle); æDT LDoDraw(drawIt,lHandle); æRI LDoDraw procedure IV-275 æC LDoDraw sets the List Manager’s drawing mode to the state specified by drawIt. If drawIt is TRUE, changes made by most List Manager calls will cause some sort of drawing to take place. If drawIt is FALSE, all cell drawing is disabled. (Two exceptions: The scroll bars are still updated after LSize, and the scroll arrows are still highlighted if the user clicks them.) The recommended use of LDoDraw is to disable drawing while you’re building a list (that is, adding rows or columns, setting or changing cell values, or setting default selections). Once you’ve finished building the list, you should then re-enable drawing. In general, drawing should be on while you’re in your event loop and dispatching events to the List Manager. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY lDoHAutoscroll,lDoVAutoscroll æFp Lists.p æC { Masks for automatic scrolling } lDoVAutoscroll = 2 {set to allow automatic vertical scrolling} lDoHAutoscroll = 1 {set to allow automatic horizontal scrolling} æKY LDraw æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LDraw(theCell: Cell;lHandle: ListHandle); æDT LDraw(theCell,lHandle); æRI LDraw procedure IV-275 æC Call LDraw after updating a cell’s data or selection status. (You can achieve the same result by invalidating the cell’s rectangle and calling LUpdate in response to the update event.) The List Manager makes its grafPort the current port, sets the clipping region to the cell’s rectangle, and calls the list definition procedure to draw the cell. It restores the clipping region and port before exiting. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LFind æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LFind(VAR offset: INTEGER;VAR len: INTEGER;theCell: Cell;lHandle: ListHandle); æDT LFind(offset,len,theCell,lHandle); æRI LFind procedure IV-274 æC Given a cell in theCell, LFind returns the offset and the length in bytes of the cell’s data. If an invalid cell is specified, offset and len are set to –1. A similar procedure, LGetCell, is more convenient to use from Pascal. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LGetCell æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LGetCell(dataPtr: Ptr;VAR dataLen: INTEGER;theCell: Cell;lHandle: ListHandle); æDT LGetCell(dataPtr,dataLen,theCell,lHandle); æRI LGetCell procedure IV-272 æC Given a cell in theCell, LGetCell copies the cell’s data to the location specified by dataPtr; dataLen is the maximum number of bytes allowed. If the data is longer than dataLen, only dataLen bytes are copied into the location specified by dataPtr. If the data is shorter than dataLen, dataLen is set to the true length of the cell’s data. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LGetSelect æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LGetSelect(next: BOOLEAN;VAR theCell: Cell;lHandle: ListHandle): BOOLEAN; æDT myVariable := LGetSelect(next,theCell,lHandle); æRI LGetSelect function IV-273 æC If next is FALSE, LGetSelect returns TRUE if the specified cell is selected, or FALSE if not. If next is TRUE, LGetSelect returns in c the cell coordinates of the next selected cell in the row that is greater than or equal to theCell. If there are no more cells in the row, it returns in theCell the cell coordinates of the next selected cell in the next row. If there are no more rows, FALSE is returned. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY lInitMsg,lDrawMsg,lHiliteMsg,lCloseMsg æFp Lists.p æC { Messages to list definition procedure } lInitMsg = 0; {initialize list, set defaults, allocate space} lDrawMsg = 1; {draw the indicated cell data} lHiliteMsg = 2; {invert (select/deselect) the state of a cell} lCloseMsg = 3; {dispose of list and any associated data} æKY LLastClick æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LLastClick(lHandle: ListHandle): Cell; æDT myVariable := LLastClick(lHandle); æRI LLastClick function IV-273 æC LLastClick returns the cell coordinates of the last cell clicked in. If no cell has been clicked in since LNew, the value returned (for both integers) is negative. Note: The value returned by this call is not the last cell double-clicked in, or the last cell selected, but merely the last cell clicked in. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LNew æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LNew(rView: Rect;dataBounds: Rect;cSize: Point;theProc: INTEGER; theWindow: WindowPtr;drawIt: BOOLEAN;hasGrow: BOOLEAN;scrollHoriz: BOOLEAN; scrollVert: BOOLEAN): ListHandle; æDT myVariable := LNew(rView,dataBounds,cSize,theProc,theWindow,drawIt,hasGrow, scrollHoriz,scrollVert); æRI LNew function IV-270 æC Call LNew to create a new list. It returns a handle to the new list. The list’s grafPort is set to theWindow’s port. If drawIt is FALSE, the list is not displayed. RView specifies, in the local coordinates of theWindow, the rectangle in which the list will be displayed. (Remember that this doesn’t include space for scroll bars. If the list, including scroll bars, is to fill the entire window, rView should be 15 points smaller in each dimension than theWindow’s portRect.) DataBounds is the rectangle for specifying the initial array dimensions of the list. For example to preallocate space for a list that’s 5 cells across by 10 cells down, you should set dataBounds to (0,0)(5,10). If you want to allocate the space for a one-column list, set dataBounds to (0,0)(1,0) and use LAddRow. CSize.h and cSize.v are the desired height and width of each cell in pixels; if they’re not specified, a default cell size is calculated (as described above). TheProc is the resource ID of your list definition procedure; for a text-only list, pass 0 and the default list definition procedure (about 150 bytes in size) will be used. The list definition procedure is called to initialize itself after all other list record fields have been initialized; thus, it can use any of the values in the list record (or set particular fields, such as the indent distance). If hasGrow is TRUE, the scroll bars are sized so that there’s room for a size box in the standard position. It’s up to the program to display the size box (using the Window Manager procedure DrawGrowIcon). If scrollHoriz is TRUE, a horizontal scroll bar is placed immediately below rView and all horizontal scrolling functions are implemented. If scrollVert is TRUE, a vertical scroll bar is placed immediately to the right of rView and all vertical scrolling functions are implemented. The visible rectangle is set to contain as many cells of cSize (or the default) as will fit into rView. If the cells do not fit exactly into rView, the visible rectangle is rounded up to the nearest cell. Scrolling will always allow all cells to be fully displayed. The selection flags are set to 0, and the active flag is set to TRUE. Note: Scrolling looks best if rView is a multiple of cSize.v in height. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LNextCell æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LNextCell(hNext: BOOLEAN;vNext: BOOLEAN;VAR theCell: Cell;lHandle: ListHandle): BOOLEAN; æDT myVariable := LNextCell(hNext,vNext,theCell,lHandle); æRI LNextCell function IV-274 æC Given a cell in theCell, LNextCell returns in theCell the next cell in the list. If both hNext and vNext are TRUE, theCell is first advanced to the next cell in the row. If there are no more cells in the row, theCell is set to the first cell in the next row. If there are no more rows, FALSE is returned. If only hNext is TRUE, theCell is advanced within the current row. If only vNext is TRUE, theCell is advanced within the current column. FALSE is returned if there are no remaining cells in the row or column. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY lOnlyOne,lExtendDrag,lNoDisjoint,lNoExtend,lNoRect,lUseSense,lNoNilHilite æFp Lists.p æC { Masks for selection flags } lOnlyOne = –128; {set if only one selection at a time} lExtendDrag = 64; {set for dragging without Shift key} lNoDisjoint = 32; {set to turn off multiple selections with click} lNoExtend = 16; {set to not extend Shift selections} lNoRect = 8; {set to not grow selections as rectangles} lUseSense = 4; {set for Shift to use sense of first cell} lNoNilHilite = 2; {set to not highlight empty cells} æKY LRect æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LRect(VAR cellRect: Rect;theCell: Cell;lHandle: ListHandle); æDT LRect(cellRect,theCell,lHandle); æRI LRect procedure IV-274 æC LRect returns in cellRect the local (QuickDraw) coordinates of the cell specified by theCell. If an invalid cell is specified, (0,0)(0,0) is returned in cellRect. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LScroll æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LScroll(dCols: INTEGER;dRows: INTEGER;lHandle: ListHandle); æDT LScroll(dCols,dRows,lHandle); æRI LScroll procedure IV-275 æC LScroll scrolls the given list by the number of columns and rows specified in dCols and dRows, either positively (down and to the right) or negatively (up and to the left). Scrolling is pinned to the list’s dataBounds. If drawing is on, LScroll does all necessary updating of the screen. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LSearch æFp Lists.p æT FUNCTION æTN $A9E7 æD FUNCTION LSearch(dataPtr: Ptr;dataLen: INTEGER;searchProc: ProcPtr;VAR theCell: Cell; lHandle: ListHandle): BOOLEAN; æDT myVariable := LSearch(dataPtr,dataLen,searchProc,theCell,lHandle); æRI LSearch function IV-274 æC LSearch searches for the first cell greater than or equal to theCell that contains the specified data. If a cell containing matching data is found, the function result TRUE is returned, and the cell coordinates are returned in theCell. If searchProc is NIL, the International Utilities Package function IUMagIDString is called to compare the specified data with the contents of each cell. If searchProc is not NIL, the routine pointed to by searchProc is called. Note: Your searchProc should have the same parameters as the IUMagIDString function. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LSetCell æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LSetCell(dataPtr: Ptr;dataLen: INTEGER;theCell: Cell;lHandle: ListHandle); æDT LSetCell(dataPtr,dataLen,theCell,lHandle); æRI LSetCell procedure IV-272 æC LSetCell places the data pointed to by dataPtr and of length dataLen into the specified cell. It replaces any data that was already in the cell. If dataLen is 0, this is equivalent to LClrCell. If theCell is not a valid cell, nothing is done. If drawing is off, you must turn drawing on and call LDraw (or LUpdate) to display the cell’s new value. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LSetSelect æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LSetSelect(setIt: BOOLEAN;theCell: Cell;lHandle: ListHandle); æDT LSetSelect(setIt,theCell,lHandle); æRI LSetSelect procedure IV-273 æC If setIt is TRUE, LSetSelect selects the cell and redraws if it is visible and was previously unselected. If setIt is FALSE, it deselects the cell and redraws if necessary. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LSize æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LSize(listWidth: INTEGER;listHeight: INTEGER;lHandle: ListHandle); æDT LSize(listWidth,listHeight,lHandle); æRI LSize procedure IV-274 æC You’ll usually call LSize immediately after the Window Manager procedure SizeWindow. It causes the bottom right of the list to be adjusted so that the list is the width and height indicated by listWidth and listHeight. The contents of the list and the scroll bars are adjusted and redrawn as necessary. The values of listWidth and listHeight do not include the scroll bars; for a list that entirely fills the window, listWidth and listHeight should be 15 fewer pixels than the portRect if both scroll bars are present. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY LUpdate æFp Lists.p æT PROCEDURE æTN $A9E7 æD PROCEDURE LUpdate(theRgn: RgnHandle;lHandle: ListHandle); æDT LUpdate(theRgn,lHandle); æRI LUpdate procedure IV-275 æC LUpdate should be called in response to an update event. TheRgn should be set to the visRgn of the list’s port (for more details, see the BeginUpdate procedure in the Window Manager chapter). It redraws any visible cells in lHandle that intersect theRgn. It also redraws the controls, if necessary. Assembly-language note: You can invoke each of the List Manager routines with a macro that has the same name as the routine preceded by an underscore. These macros expand to invoke to trap macro _Pack 0. The package determines which routine to execute from a routine selector, an integer that’s passed to it in a word on the stack. The routine selectors are as follows: lActivate .EQU 0 lAutoScroll .EQU 16 lAddColumn .EQU 4 lCellSize .EQU 20 lAddRow .EQU 8 lClick .EQU 24 lAddToCell .EQU 12 lClrCell .EQU 28 lDelColumn .EQU 32 lNew .EQU 68 lDelRow .EQU 36 lNextCell .EQU 72 lDispose .EQU 40 lRect .EQU 76 lDoDraw .EQU 44 lScroll .EQU 80 lDraw .EQU 48 lSearch .EQU 84 lFind .EQU 52 lSetCell .EQU 88 lGetCell .EQU 56 lSetSelect .EQU 92 lGetSelect .EQU 60 lSize .EQU 96 lLastClick .EQU 64 lUpdate .EQU 100 æKY Memory.p æKL ApplicZone BlockMove CompactMem DisposHandle DisposPtr EmptyHandle FreeMem GetApplLimit GetHandleSize GetPtrSize GetZone GZSaveHnd HandleZone HClrRBit HGetState HLock HNoPurge HPurge HSetRBit HSetState HUnlock InitApplZone InitZone MaxApplZone MaxBlock MaxMem MemError MFFreeMem MFMaxMem MFTempDisposHandle MFTempHLock MFTempHUnlock MFTempNewHandle MFTopMem MoreMasters MoveHHi NewEmptyHandle NewHandle NewHandleClear NewHandleSys NewHandleSysClear NewPtr NewPtrClear NewPtrSys NewPtrSysClear PtrZone PurgeMem PurgeSpace ReallocHandle RecoverHandle ResrvMem SetApplBase SetApplLimit SetGrowZone SetHandleSize SetPtrSize SetZone StackSpace StripAddress SystemZone TopMem maxSize Size THz Zone æKY Zone,THz æFp Memory.p æT TYPE æC THz = ^Zone; Zone = RECORD bkLim: Ptr; purgePtr: Ptr; hFstFree: Ptr; zcbFree: LONGINT; gzProc: ProcPtr; moreMast: INTEGER; flags: INTEGER; cntRel: INTEGER; maxRel: INTEGER; cntNRel: INTEGER; maxNRel: INTEGER; cntEmpty: INTEGER; cntHandles: INTEGER; minCBFree: LONGINT; purgeProc: ProcPtr; sparePtr: Ptr; allocPtr: Ptr; heapData: INTEGER; END; »Structure of Heap Zones Each heap zone begins with a 52-byte zone header and ends with a 12-byte zone trailer (see Figure 11). The header contains all the information the Memory Manager needs about that heap zone; the trailer is just a minimum-size free block (described in the next section) placed at the end of the zone as a marker. All the remaining space between the header and trailer is available for allocation. In Pascal, a heap zone is defined as a zone record of type Zone. It’s always referred to with a zone pointer of type THz (“the heap zone”): TYPE THz = ^Zone; Zone = RECORD bkLim: Ptr; {zone trailer block} purgePtr: Ptr; {used internally} hFstFree: Ptr; {first free master pointer} zcbFree: LONGINT; {number of free bytes} gzProc: ProcPtr; {grow zone function} moreMast: INTEGER; {master pointers to allocate} flags: INTEGER; {used internally} cntRel: INTEGER; {not used} maxRel: INTEGER; {not used} cntNRel: INTEGER; {not used} maxNRel: INTEGER; {not used} cntEmpty: INTEGER; {not used} cntHandles: INTEGER; {not used} minCBFree: LONGINT; {not used} purgeProc: ProcPtr; {purge warning procedure} sparePtr: Ptr; {used internally} allocPtr: Ptr; {used internally} heapData: INTEGER {first usable byte in zone} END; Warning: The fields of the zone header are for the Memory Manager’s own internal use. You can examine the contents of the zone’s fields, but in general it doesn’t make sense for your program to try to change them. The few exceptions are noted below in the discussions of the specific fields. BkLim is a pointer to the zone’s trailer block. Since the trailer is the last block in the zone, bkLim is a pointer to the byte following the last byte of usable space in the zone. HFstFree is a pointer to the first free master pointer in the zone. Instead of just allocating space for one master pointer each time a relocatable block is created, the Memory Manager “preallocates” several master pointers at a time; as a group they form a nonrelocatable block. The moreMast field of the zone record tells the Memory Manager how many master pointers at a time to preallocate for this zone. Note: Master pointers are allocated 32 at a time for the system heap zone and 64 at a time for the application zone; this may be different on future versions of the Macintosh. All master pointers that are allocated but not currently in use are linked together into a list beginning in the hFstFree field. When you allocate a new relocatable block, the Memory Manager removes the first available master pointer from this list, sets it to point to the new block, and returns its address to you as a handle to the block. (If the list is empty, it allocates a fresh block of moreMast master pointers.) When you release a relocatable block, its master pointer isn’t released, but is linked onto the beginning of the list to be reused. Thus the amount of space devoted to master pointers can increase, but can never decrease until the zone is reinitialized. The zcbFree field always contains the number of free bytes remaining in the zone. As blocks are allocated and released, the Memory Manager adjusts zcbFree accordingly. This number represents an upper limit on the size of block you can allocate from this heap zone. Warning: It may not actually be possible to allocate a block as big as zcbFree bytes. Because nonrelocatable and locked blocks can’t be moved, it isn’t always possible to collect all the free space into a single block by compaction. The gzProc field is a pointer to the grow zone function. You can supply a pointer to your own grow zone function when you create a new heap zone and can change it at any time. Warning: Don’t store directly into the gzProc field; if you want to supply your own grow zone function, you must do so with a procedure call (InitZone or SetGrowZone). PurgeProc is a pointer to the zone’s purge warning procedure, or NIL if there is none. The Memory Manager will call this procedure before it purges a block from the zone. Warning: Whenever you call the Resource Manager with SetResPurge(TRUE), it installs its own purge warning procedure, overriding any purge warning procedure you’ve specified to the Memory Manager; for further details, see the Resource Manager chapter. The last field of a zone record, heapData, is a dummy field marking the bottom of the zone’s usable memory space. HeapData nominally contains an integer, but this integer has no significance in itself—it’s just the first two bytes in the block header of the first block in the zone. The purpose of the heapData field is to give you a way of locating the effective bottom of the zone. For example, if myZone is a zone pointer, then @(myZone^.heapData) is a pointer to the first usable byte in the zone, just as myZone^.bkLim is a pointer to the byte following the last usable byte in the zone. æKY ApplicZone æFp Memory.p æT FUNCTION æD FUNCTION ApplicZone: THz; æDT myVariable := ApplicZone; æRI ApplicZone function II-32, N83-1 æC [Not in ROM] ApplicZone returns a pointer to the original application heap zone. Assembly-language note: The global variable ApplZone contains a pointer to the original application heap zone. æKY BlockMove æFp Memory.p æT PROCEDURE æTN $A02E æD PROCEDURE BlockMove(srcPtr: Ptr;destPtr: Ptr;byteCount: Size); æDT BlockMove(srcPtr,destPtr,byteCount); æRI BlockMove procedure II-44 æC Trap macro _BlockMove On entry A0: sourcePtr (pointer) A1: destPtr (pointer) D0: byteCount (long word) On exit D0: result code (word) BlockMove moves a block of byteCount consecutive bytes from the address designated by sourcePtr to that designated by destPtr. No pointers are updated. BlockMove works correctly even if the source and destination blocks overlap. Result codes noErr No error æKY CompactMem æFp Memory.p æT FUNCTION æTN $A04C æD FUNCTION CompactMem(cbNeeded: Size): Size; æDT myVariable := CompactMem(cbNeeded); æMM æRT 51 æRI CompactMem function II-39, N51-1 æC Trap macro _CompactMem _CompactMem ,SYS (applies to system heap) On entry D0: cbNeeded (long word) On exit D0: function result (long word) CompactMem compacts the current heap zone by moving relocatable blocks down and collecting free space together until a contiguous block of at least cbNeeded free bytes is found or the entire zone is compacted; it doesn’t purge any purgeable blocks. CompactMem returns the size in bytes of the largest contiguous free block remaining. Note that it doesn’t actually allocate the block. Result codes noErr No error [Pascal only] æKY DisposHandle æFp Memory.p æT PROCEDURE æTN $A023 æD PROCEDURE DisposHandle(h: Handle); æDT DisposHandle(h); æMM æRI DisposHandle procedure I-76, 80, II-33, N8-1, P-51, 168 æC Trap macro _DisposHandle On entry A0: h (handle) On exit D0: result code (word) DisposHandle releases the memory occupied by the relocatable block whose handle is h. Warning: After a call to DisposHandle, all handles to the released block become invalid and should not be used again. Any subsequent calls to DisposHandle using an invalid handle will damage the master pointer list. Result codes noErr No error memWZErr Attempt to operate on a free block æKY DisposPtr æFp Memory.p æT PROCEDURE æTN $A01F æD PROCEDURE DisposPtr(p: Ptr); æDT DisposPtr(p); æMM æRI DisposPtr procedure I-75, 79, II-36, P-51, 169 æC Trap macro _DisposPtr On entry A0: p (pointer) On exit D0: result code (word) DisposPtr releases the memory occupied by the nonrelocatable block pointed to by p. Warning: After a call to DisposPtr, all pointers to the released block become invalid and should not be used again. Any subsequent calls to DisposPtr using an invalid pointer will damage the master pointer list. Result codes noErr No error memWZErr Attempt to operate on a free block æKY EmptyHandle æFp Memory.p æT PROCEDURE æTN $A02B æD PROCEDURE EmptyHandle(h: Handle); æDT EmptyHandle(h); æMM æRI EmptyHandle procedure II-40 æC Trap macro _EmptyHandle On entry A0: h (handle) On exit A0: h (handle) D0: result code (word) EmptyHandle purges the relocatable block whose handle is h from its heap zone and sets its master pointer to NIL (making it an empty handle). If h is already empty, EmptyHandle does nothing. Note: Since the space occupied by the block’s master pointer itself remains allocated, all handles pointing to it remain valid but empty. When you later reallocate space for the block with ReallocHandle, the master pointer will be updated, causing all existing handles to access the new block correctly. The block whose handle is h must be unlocked, but need not be purgeable. Result codes noErr No error memWZErr Attempt to operate on a free block memPurErr Attempt to purge a locked block æKY FreeMem æFp Memory.p æT FUNCTION æTN $A01C æD FUNCTION FreeMem: LONGINT; æDT myVariable := FreeMem; æMM æRI FreeMem function II-38 æC Trap macro _FreeMem _FreeMem ,SYS (applies to system heap) On exit D0: function result (long word) FreeMem returns the total amount of free space in the current heap zone, in bytes. Note that it usually isn’t possible to allocate a block of this size, because of fragmentation due to nonrelocatable or locked blocks. Result codes noErr No error [Pascal only] æKY GetApplLimit æFp Memory.p æT FUNCTION æD FUNCTION GetApplLimit: Ptr; æDT myVariable := GetApplLimit; æRI GetApplLimit function II-29 æC GetApplLimit returns the current application heap limit. It can be used in conjunction with SetApplLimit, described below, to determine and then change the application heap limit. Assembly-language note: The global variable ApplLimit contains the current application heap limit. æKY GetHandleSize æFp Memory.p æT FUNCTION æTN $A025 æD FUNCTION GetHandleSize(h: Handle): Size; æDT myVariable := GetHandleSize(h); æRI GetHandleSize function II-33, N54-1, N63-1 æC Trap macro _GetHandleSize On entry A0: h (handle) On exit D0: if >= 0, function result (long word) if < 0, result code (word) GetHandleSize returns the logical size, in bytes, of the relocatable block whose handle is h. In case of an error, GetHandleSize returns 0. Assembly-language note: Recall that the trap dispatcher sets the condition codes before returning from a trap by testing the low-order word of register D0 with a TST.W instruction. Since the block size returned in D0 by _GetHandleSize is a full 32-bit long word, the word-length test sets the condition codes incorrectly in this case. To branch on the contents of D0, use your own TST.L instruction on return from the trap to test the full 32 bits of the register. Result codes noErr No error [Pascal only] nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY GetPtrSize æFp Memory.p æT FUNCTION æTN $A021 æD FUNCTION GetPtrSize(p: Ptr): Size; æDT myVariable := GetPtrSize(p); æRI GetPtrSize function II-37 æC Trap macro _GetPtrSize On entry A0: p (pointer) On exit D0: if >= 0, function result (long word) if < 0, result code (word) GetPtrSize returns the logical size, in bytes, of the nonrelocatable block pointed to by p. In case of an error, GetPtrSize returns 0. Assembly-language note: Recall that the trap dispatcher sets the condition codes before returning from a trap by testing the low-order word of register D0 with a TST.W instruction. Since the block size returned in D0 by _GetPtrSize is a full 32-bit long word, the word-length test sets the condition codes incorrectly in this case. To branch on the contents of D0, use your own TST.L instruction on return from the trap to test the full 32 bits of the register. Result codes noErr No error [Pascal only] memWZErr Attempt to operate on a free block æKY GetZone æFp Memory.p æT FUNCTION æTN $A11A æD FUNCTION GetZone: THz; æDT myVariable := GetZone; æRI GetZone function II-31 æC Trap macro _GetZone On exit A0: function result (pointer) D0: result code (word) GetZone returns a pointer to the current heap zone. Assembly-language note: The global variable TheZone contains a pointer to the current heap zone. Result codes noErr No error æKY GZSaveHnd æFp Memory.p æT FUNCTION æD FUNCTION GZSaveHnd: Handle; æDT myVariable := GZSaveHnd; æRI GZSaveHnd function II-43 æC GZSaveHnd returns a handle to a relocatable block that must not be moved by the grow zone function, or NIL if there is no such block. Your grow zone function must be sure to call GZSaveHnd; if a handle is returned, it must ensure that this block is not moved. Assembly-language note: You can find the same handle in the global variable GZRootHnd. æKY HandleZone æFp Memory.p æT FUNCTION æTN $A126 æD FUNCTION HandleZone(h: Handle): THz; æDT myVariable := HandleZone(h); æRI HandleZone function II-34 æC Trap macro _HandleZone On entry A0: h (handle) On exit A0: function result (pointer) D0: result code (word) HandleZone returns a pointer to the heap zone containing the relocatable block whose handle is h. In case of an error, the result returned by HandleZone is undefined and should be ignored. Warning: If handle h is empty (points to a NIL master pointer), HandleZone returns a pointer to the current heap zone. Result codes noErr No error memWZErr Attempt to operate on a free block æKY HClrRBit æFp Memory.p æT PROCEDURE æTN $A068 æD PROCEDURE HClrRBit(h: Handle); æDT HClrRBit(h); æRT 2 æRI HClrRBit procedure IV-79, N2-3 æC Trap macro _HClrRBit On entry A0: h (handle) On exit D0: result code (word) HClrRBit clears the resource flag of a relocatable block’s master pointer. æKY HGetState æFp Memory.p æT FUNCTION æTN $A069 æD FUNCTION HGetState(h: Handle): SignedByte; æDT myVariable := HGetState(h); æRT 2 æRI HGetState function IV-79, N2-3 æC Trap macro _HGetState On entry A0: h (handle) On exit D0: flags (byte) HGetState returns the byte that contains the flags of the master pointer for the given handle; it’s used in conjunction with HSetState to save and restore the state of the flags contained in this byte. You can save this byte, change the state of any of the flags (using the routines described above), and then restore their original state by passing the byte back to the HSetState procedure (described below). æKY HLock æFp Memory.p æT PROCEDURE æTN $A029 æD PROCEDURE HLock(h: Handle); æDT HLock(h); æRT 2 æRI HLock procedure II-41, N2-3 æC The master pointer associated with each handle contains flags for use by the Memory Manager. Routines are provided for setting and clearing each of these flags, as well as for saving and restoring the entire byte. Warning: Failure to use these routines virtually guarantees incompatibility with future versions of the Macintosh. You should not set and clear these flags directly. The HLock and HUnlock procedures lock and unlock a given relocatable block by setting and clearing the lock flag. The HPurge and HNoPurge mark a given relocatable block as purgeable or unpurgeable by setting and clearing the purge flag. A third flag, the resource flag, is used internally by the Resource Manager. The HSetRBit and HClrRBit procedures set and clear this flag. The HSetState and HGetState routines let you save and restore the state of the flags byte. PROCEDURE HLock (h: Handle); Trap macro _HLock On entry A0: h (handle) On exit D0: result code (word) HLock locks a relocatable block, preventing it from being moved within its heap zone. If the block is already locked, HLock does nothing. Warning: To prevent heap fragmentation, you should always call MoveHHi before locking a relocatable block. Result codes noErr No error nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY HNoPurge æFp Memory.p æT PROCEDURE æTN $A04A æD PROCEDURE HNoPurge(h: Handle); æDT HNoPurge(h); æRT 2 æRI HNoPurge procedure II-42, N2-3 æC Trap macro _HNoPurge On entry A0: h (handle) On exit D0: result code (word) HNoPurge marks a relocatable block as unpurgeable. If the block is already unpurgeable, HNoPurge does nothing. Result codes noErr No error nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY HPurge æFp Memory.p æT PROCEDURE æTN $A049 æD PROCEDURE HPurge(h: Handle); æDT HPurge(h); æRT 2 æRI HPurge procedure II-41 æC Trap macro _HPurge On entry A0: h (handle) On exit D0: result code (word) HPurge marks a relocatable block as purgeable. If the block is already purgeable, HPurge does nothing. Note: If you call HPurge on a locked block, it won’t unlock the block, but it will mark the block as purgeable. If you later call HUnlock, the block will be subject to purging. Result codes noErr No error nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY HSetRBit æFp Memory.p æT PROCEDURE æTN $A067 æD PROCEDURE HSetRBit(h: Handle); æDT HSetRBit(h); æRT 2 æRI HSetRBit procedure IV-79, N2-3 æC Trap macro _HSetRBit On entry A0: h (handle) On exit D0: result code (word) HSetRBit sets the resource flag of a relocatable block’s master pointer. æKY HSetState æFp Memory.p æT PROCEDURE æTN $A06A æD PROCEDURE HSetState(h: Handle;flags: SignedByte); æDT HSetState(h,flags); æRT 2 æRI HSetState procedure IV-80, N2-3 æC Trap macro _HSetState On entry A0: h (handle) D0: flags (byte) On exit D0: result code (word) HSetState is used in conjunction with HGetState; it sets the byte that contains the flags of the master pointer for the given handle to the byte specified by flags. æKY HUnlock æFp Memory.p æT PROCEDURE æTN $A02A æD PROCEDURE HUnlock(h: Handle); æDT HUnlock(h); æRT 2 æRI HUnlock procedure II-41, N2-3 æC The master pointer associated with each handle contains flags for use by the Memory Manager. Routines are provided for setting and clearing each of these flags, as well as for saving and restoring the entire byte. Warning: Failure to use these routines virtually guarantees incompatibility with future versions of the Macintosh. You should not set and clear these flags directly. The HLock and HUnlock procedures lock and unlock a given relocatable block by setting and clearing the lock flag. The HPurge and HNoPurge mark a given relocatable block as purgeable or unpurgeable by setting and clearing the purge flag. A third flag, the resource flag, is used internally by the Resource Manager. The HSetRBit and HClrRBit procedures set and clear this flag. The HSetState and HGetState routines let you save and restore the state of the flags byte. PROCEDURE HUnlock (h: Handle); Trap macro _HUnlock On entry A0: h (handle) On exit D0: result code (word) HUnlock unlocks a relocatable block, allowing it to be moved within its heap zone. If the block is already unlocked, HUnlock does nothing. Result codes noErr No error nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY InitApplZone æFp Memory.p æT PROCEDURE æTN $A02C æD PROCEDURE InitApplZone; æDT InitApplZone; æMM æRI InitApplZone procedure II-28, N64-2 æC Trap macro _InitApplZone On exit D0: result code (word) InitApplZone initializes the application heap zone and makes it the current zone. The contents of any previous application zone are lost; all previously existing blocks in that zone are discarded. The zone’s grow zone function is set to NIL. InitApplZone is called by the Segment Loader when starting up an application; you shouldn’t normally need to call it. Warning: Reinitializing the application zone from within a running program is tricky, since the program’s code itself normally resides in the application zone. To do it safely, the code containing the InitApplZone call cannot be in the application zone. Result codes noErr No error æKY InitZone æFp Memory.p æT PROCEDURE æTN $A019 æD PROCEDURE InitZone(pgrowZone: ProcPtr;cmoreMasters: INTEGER;limitPtr: Ptr; startPtr: Ptr); æDT InitZone(pgrowZone,cmoreMasters,limitPtr,startPtr); æMM æRI InitZone procedure II-29 æC Trap macro _InitZone On entry A0: pointer to parameter block Parameter block 0 startPtr pointer 4 limitPtr pointer 8 cMoreMasters word 10 pGrowZone pointer On exit D0: result code (word) InitZone creates a new heap zone, initializes its header and trailer, and makes it the current zone. The startPtr parameter is a pointer to the first byte of the new zone; limitPtr points to the first byte beyond the end of the zone. The new zone will occupy memory addresses from ORD(startPtr) through ORD(limitPtr)–1. CMoreMasters tells how many master pointers should be allocated at a time for the new zone. This number of master pointers are created initially; should more be needed later, they’ll be added in increments of this same number. The pGrowZone parameter is a pointer to the grow zone function for the new zone, if any. If you’re not defining a grow zone function for this zone, pass NIL. The new zone includes a 52-byte header and a 12-byte trailer, so its actual usable space runs from ORD(startPtr)+52 through ORD(limitPtr)–13. In addition, there’s an eight-byte header for the master pointer block, as well as four bytes for each master pointer, within this usable area. Thus the total available space in the zone, in bytes, is initially ORD(limitPtr) – ORD(startPtr) – 64 – (8 + (4*cMoreMasters)) This number must not be less than 0. Note that the amount of available space in the zone will decrease as more master pointers are allocated. Result codes noErr No error æKY MaxApplZone æFp Memory.p æT PROCEDURE æTN $A063 æD PROCEDURE MaxApplZone; æDT MaxApplZone; æRT 103 æRI MaxApplZone procedure II-30, IV-77, 83, N39-1, N103 æC Trap macro _MaxApplZone On exit D0: result code (word) MaxApplZone expands the application heap zone to the application heap limit without purging any blocks currently in the zone. If the zone already extends to the limit, it won’t be changed. Assembly-language note: To expand the application heap zone to the application heap limit from assembly language, call this Pascal procedure from your program. Result codes noErr No error æKY MaxBlock æFp Memory.p æT FUNCTION æTN $A061 æD FUNCTION MaxBlock: LONGINT; æDT myVariable := MaxBlock; æRI MaxBlock function IV-77 æC Trap macro _MaxBlock _MaxBlock ,SYS (applies to system heap) On exit D0: function result (word) MaxBlock returns the maximum contiguous space in bytes that could be obtained by compacting the current zone (without actually doing the compaction). æKY MaxMem æFp Memory.p æT FUNCTION æTN $A11D æD FUNCTION MaxMem(VAR grow: Size): Size; æDT myVariable := MaxMem(grow); æRI MaxMem function II-38 æC Trap macro _MaxMem _MaxMem ,SYS (applies to system heap) On exit D0: function result (long word) A0: grow (long word) MaxMem compacts the current heap zone and purges all purgeable blocks from the zone. It returns as its result the size in bytes of the largest contiguous free block in the zone after the compaction. If the current zone is the original application heap zone, the grow parameter is set to the maximum number of bytes by which the zone can grow. For any other heap zone, grow is set to 0. MaxMem doesn’t actually expand the zone or call its grow zone function. Result codes noErr No error [Pascal only] æKY maxSize æFp Memory.p æC maxSize = $800000; {Max data block size is 8 megabytes} æKY MemError æFp Memory.p æT FUNCTION æD FUNCTION MemError: OSErr; æDT myVariable := MemError; æRT 7 æRI MemError function II-44, N7-2 æC All Memory Manager routines (including the RecoverHandle function) return a result code that you can examine by calling the MemError function. Assembly-language note: The trap _RecoverHandle doesn’t return a result code in register D0. The result code of the most recent call, however, is always stored in the global variable MemErr. FUNCTION MemError : OSErr; [Not in ROM] MemError returns the result code produced by the last Memory Manager routine called directly by your program. (OSErr is an Operating System Utility data type declared as INTEGER.) Assemby-language note: To get a routine’s result code from assembly language, look in register D0 on return from the routine (except for certain routines as noted). æKY MFFreeMem æFp Memory.p æT FUNCTION æTN $A88F æD FUNCTION MFFreeMem: LONGINT; æDT myVariable := MFFreeMem; æKY MFMaxMem æFp Memory.p æT FUNCTION æTN $A88F æD FUNCTION MFMaxMem(VAR grow: Size): Size; æDT myVariable := MFMaxMem(grow); æKY MFTempDisposHandle æFp Memory.p æT PROCEDURE æTN $A88F æD PROCEDURE MFTempDisposHandle(h: Handle;VAR resultCode: OSErr); æDT MFTempDisposHandle(h,resultCode); æKY MFTempHLock æFp Memory.p æT PROCEDURE æTN $A88F æD PROCEDURE MFTempHLock(h: Handle;VAR resultCode: OSErr); æDT MFTempHLock(h,resultCode); æKY MFTempHUnlock æFp Memory.p æT PROCEDURE æTN $A88F æD PROCEDURE MFTempHUnlock(h: Handle;VAR resultCode: OSErr); æDT MFTempHUnlock(h,resultCode); æKY MFTempNewHandle æFp Memory.p æT FUNCTION æTN $A88F æD FUNCTION MFTempNewHandle(logicalSize: Size;VAR resultCode: OSErr): Handle; æDT myVariable := MFTempNewHandle(logicalSize,resultCode); æRT 205 æKY MFTopMem æFp Memory.p æT FUNCTION æTN $A88F æD FUNCTION MFTopMem: Ptr; æDT myVariable := MFTopMem; æKY MoreMasters æFp Memory.p æT PROCEDURE æTN $A036 æD PROCEDURE MoreMasters; æDT MoreMasters; æMM æRT 53 æRI MoreMasters procedure II-31, N53 æC Trap macro _MoreMasters MoreMasters allocates another block of master pointers in the current heap zone. This procedure is usually called very early in an application. Result codes noErr No error memFullErr Not enough room in heap zone æKY MoveHHi æFp Memory.p æT PROCEDURE æTN $A064 æD PROCEDURE MoveHHi(h: Handle); æDT MoveHHi(h); æMM æRT 103, 111 æRI MoveHHi procedure II-44, IV-77, 83, N103, N111 æC [Not in 64K ROM] Trap macro _MoveHHi On entry A0: h (handle) On exit D0: result code (word) MoveHHi moves the relocatable block whose handle is h toward the top of the current heap zone, until the block hits either a nonrelocatable block, a locked relocatable block, or the last block in the current heap zone. By calling MoveHHi before you lock a relocatable block, you can avoid fragmentation of the heap, as well as make room for future pointers as low in the heap as possible. Result codes noErr No error nilHandleErr NIL master pointer memLockedErr Block is locked æKY NewEmptyHandle æFp Memory.p æT FUNCTION æTN $A066 æD FUNCTION NewEmptyHandle: Handle; æDT myVariable := NewEmptyHandle; æMM æRI NewEmptyHandle function IV-78 æC Trap macro _NewEmptyHandle _NewEmptyHandle ,SYS (applies to system heap) On exit A0: function result (handle) D0: result code (word) NewEmptyHandle is similar in function to NewHandle except that it does not allocate any space; the handle returned is empty (in other words, it points to a NIL master pointer). NewEmptyHandle is used extensively by the Resource Manager; you may not need to use it. æKY NewHandle æFp Memory.p æT FUNCTION æTN $A122 æD FUNCTION NewHandle(byteCount: Size): Handle; æDT myVariable := NewHandle(byteCount); æMM æRT 7, 117, 205 æRI NewHandle function I-76, 80, II-32, N7-2, N117-17, P-51, 177 æC Trap macro _NewHandle _NewHandle ,SYS (applies to system heap) _NewHandle ,CLEAR (clears allocated block) _NewHandle ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (handle) D0: result code (word) NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the current heap zone and then return a handle to it. The new block will be unlocked and unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL. NewHandle will pursue all available avenues to create a free block of the requested size, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY NewHandleClear æFp Memory.p æT FUNCTION æTN $A122 æD FUNCTION NewHandleClear(byteCount: Size): Handle; æDT myVariable := NewHandleClear(byteCount); æRT 219 æC Trap macro _NewHandle _NewHandle ,SYS (applies to system heap) _NewHandle ,CLEAR (clears allocated block) _NewHandle ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (handle) D0: result code (word) NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the current heap zone and then return a handle to it. The new block will be unlocked and unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL. NewHandle will pursue all available avenues to create a free block of the requested size, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY NewHandleSys æFp Memory.p æT FUNCTION æTN $A122 æD FUNCTION NewHandleSys(byteCount: Size): Handle; æDT myVariable := NewHandleSys(byteCount); æRT 219 æC Trap macro _NewHandle _NewHandle ,SYS (applies to system heap) _NewHandle ,CLEAR (clears allocated block) _NewHandle ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (handle) D0: result code (word) NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the current heap zone and then return a handle to it. The new block will be unlocked and unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL. NewHandle will pursue all available avenues to create a free block of the requested size, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY NewHandleSysClear æFp Memory.p æT FUNCTION æTN $A122 æD FUNCTION NewHandleSysClear(byteCount: Size): Handle; æDT myVariable := NewHandleSysClear(byteCount); æRT 219 æC Trap macro _NewHandle _NewHandle ,SYS (applies to system heap) _NewHandle ,CLEAR (clears allocated block) _NewHandle ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (handle) D0: result code (word) NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the current heap zone and then return a handle to it. The new block will be unlocked and unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL. NewHandle will pursue all available avenues to create a free block of the requested size, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY NewPtr æFp Memory.p æT FUNCTION æTN $A11E æD FUNCTION NewPtr(byteCount: Size): Ptr; æDT myVariable := NewPtr(byteCount); æMM æRI NewPtr function I-75, 79, II-36, P-51, 177 æC Trap macro _NewPtr _NewPtr ,SYS (applies to system heap) _NewPtr ,CLEAR (clears allocated block) _NewPtr ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (pointer) D0: result code (word) NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the current heap zone and then return a pointer to it. If logicalSize bytes can’t be allocated, NewPtr returns NIL. NewPtr will pursue all available avenues to create a free block of the requested size at the lowest possible location in the heap zone, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY NewPtrClear æFp Memory.p æT FUNCTION æTN $A11E æD FUNCTION NewPtrClear(byteCount: Size): Ptr; æDT myVariable := NewPtrClear(byteCount); æRT 219 æC Trap macro _NewPtr _NewPtr ,SYS (applies to system heap) _NewPtr ,CLEAR (clears allocated block) _NewPtr ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (pointer) D0: result code (word) NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the current heap zone and then return a pointer to it. If logicalSize bytes can’t be allocated, NewPtr returns NIL. NewPtr will pursue all available avenues to create a free block of the requested size at the lowest possible location in the heap zone, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY NewPtrSys æFp Memory.p æT FUNCTION æTN $A11E æD FUNCTION NewPtrSys(byteCount: Size): Ptr; æDT myVariable := NewPtrSys(byteCount); æRT 219 æC Trap macro _NewPtr _NewPtr ,SYS (applies to system heap) _NewPtr ,CLEAR (clears allocated block) _NewPtr ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (pointer) D0: result code (word) NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the current heap zone and then return a pointer to it. If logicalSize bytes can’t be allocated, NewPtr returns NIL. NewPtr will pursue all available avenues to create a free block of the requested size at the lowest possible location in the heap zone, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY NewPtrSysClear æFp Memory.p æT FUNCTION æTN $A11E æD FUNCTION NewPtrSysClear(byteCount: Size): Ptr; æDT myVariable := NewPtrSysClear(byteCount); æRT 219 æC Trap macro _NewPtr _NewPtr ,SYS (applies to system heap) _NewPtr ,CLEAR (clears allocated block) _NewPtr ,SYS,CLEAR (applies to system heap and clears allocated block) On entry D0: logicalSize (long word) On exit A0: function result (pointer) D0: result code (word) NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the current heap zone and then return a pointer to it. If logicalSize bytes can’t be allocated, NewPtr returns NIL. NewPtr will pursue all available avenues to create a free block of the requested size at the lowest possible location in the heap zone, including compacting the heap zone, increasing its size, purging blocks from it, and calling its grow zone function, if any. Result codes noErr No error memFullErr Not enough room in heap zone æKY PtrZone æFp Memory.p æT FUNCTION æTN $A148 æD FUNCTION PtrZone(p: Ptr): THz; æDT myVariable := PtrZone(p); æRI PtrZone function II-38 æC Trap macro _PtrZone On entry A0: p (pointer) On exit A0: function result (pointer) D0: result code (word) PtrZone returns a pointer to the heap zone containing the nonrelocatable block pointed to by p. In case of an error, the result returned by PtrZone is undefined and should be ignored. Result codes noErr No error memWZErr Attempt to operate on a free block æKY PurgeMem æFp Memory.p æT PROCEDURE æTN $A04D æD PROCEDURE PurgeMem(cbNeeded: Size); æDT PurgeMem(cbNeeded); æMM æRT 51 æRI PurgeMem procedure II-40, N51-1 æC Trap macro _PurgeMem _PurgeMem ,SYS (applies to system heap) On entry D0: cbNeeded (long word) On exit D0: result code (word) PurgeMem sequentially purges blocks from the current heap zone until a contiguous block of at least cbNeeded free bytes is created or the entire zone is purged; it doesn’t compact the heap zone. Only relocatable, unlocked, purgeable blocks can be purged. Note that PurgeMem doesn’t actually allocate the block. Result codes noErr No error memFullErr Not enough room in heap zone æKY PurgeSpace æFp Memory.p æT PROCEDURE æTN $A062 æD PROCEDURE PurgeSpace(VAR total: LONGINT;VAR contig: LONGINT); æDT PurgeSpace(total,contig); æRI PurgeSpace procedure IV-78 æC Trap macro _PurgeSpace _PurgeSpace ,SYS (applies to system heap) On exit A0: contig (long word) D0: total (long word) PurgeSpace returns in total the total amount of space in bytes that could be obtained by a general purge (without actually doing the purge); this amount includes space that is already free. The maximum contiguous space in bytes (including already free space) that could be obtained by a purge is returned in contig. æKY ReallocHandle æFp Memory.p æT PROCEDURE æTN $A027 æD PROCEDURE ReallocHandle(h: Handle;byteCount: Size); æDT ReallocHandle(h,byteCount); æMM æRI ReallocHandle procedure II-35 æC Trap macro _ReallocHandle On entry A0: h (handle) D0: logicalSize (long word) On exit D0: result code (word) ReallocHandle allocates a new relocatable block with a logical size of logicalSize bytes. It then updates handle h by setting its master pointer to point to the new block. The main use of this procedure is to reallocate space for a block that has been purged. Normally h is an empty handle, but it need not be: If it points to an existing block, that block is released before the new block is created. In case of an error, no new block is allocated and handle h is left unchanged. Result codes noErr No error memFullErr Not enough room in heap zone memWZErr Attempt to operate on a free block memPurErr Attempt to purge a locked block æKY RecoverHandle æFp Memory.p æT FUNCTION æTN $A128 æD FUNCTION RecoverHandle(p: Ptr): Handle; æDT myVariable := RecoverHandle(p); æMM æRT 23 æRI RecoverHandle function II-35, N8-1, N23-1 æC Trap macro _RecoverHandle _RecoverHandle ,SYS (applies to system heap) On entry A0: p (pointer) On exit A0: function result (handle) D0: unchanged RecoverHandle returns a handle to the relocatable block pointed to by p. Assembly-language note: The trap _RecoverHandle doesn’t return a result code in register D0; the previous contents of D0 are preserved unchanged. Result codes noErr No error [Pascal only] æKY ResrvMem æFp Memory.p æT PROCEDURE æTN $A040 æD PROCEDURE ResrvMem(cbNeeded: Size); æDT ResrvMem(cbNeeded); æMM æRI ResrvMem procedure II-39 æC Trap macro _ResrvMem _ResrvMem ,SYS (applies to system heap) On entry D0: cbNeeded (long word) On exit D0: result code (word) ResrvMem creates free space for a block of cbNeeded contiguous bytes at the lowest possible position in the current heap zone. It will try every available means to place the block as close as possible to the bottom of the zone, including moving other blocks upward, expanding the zone, or purging blocks from it. Note that ResrvMem doesn’t actually allocate the block. Note: When you allocate a relocatable block that you know will be locked for long periods of time, call ResrvMem first. This reserves space for the block near the bottom of the heap zone, where it will interfere with compaction as little as possible. It isn’t necessary to call ResrvMem for a nonrelocatable block; NewPtr calls it automatically. It’s also called automatically when locked resources are read into memory. Result codes noErr No error memFullErr Not enough room in heap zone æKY SetApplBase æFp Memory.p æT PROCEDURE æTN $A057 æD PROCEDURE SetApplBase(startPtr: Ptr); æDT SetApplBase(startPtr); æMM æRI SetApplBase procedure II-28 æC Trap macro _SetAppBase On entry A0: startPtr (pointer) On exit D0: result code (word) SetApplBase changes the starting address of the application heap zone to the address designated by startPtr, and then calls InitApplZone. SetApplBase is normally called only by the system itself; you should never need to call this procedure. Since the application heap zone begins immediately following the end of the system zone, changing its starting address has the effect of changing the size of the system zone. The system zone can be made larger, but never smaller; if startPtr points to an address lower than the current end of the system zone, it’s ignored and the application zone’s starting address is left unchanged. Warning: Like InitApplZone, SetApplBase is a tricky operation, because the program’s code itself normally resides in the application heap zone. To do it safely, the code containing the SetApplBase call cannot be in the application zone. Result codes noErr No error æKY SetApplLimit æFp Memory.p æT PROCEDURE æTN $A02D æD PROCEDURE SetApplLimit(zoneLimit: Ptr); æDT SetApplLimit(zoneLimit); æRI SetApplLimit procedure II-30 æC Trap macro _SetApplLimit On entry A0: zoneLimit (pointer) On exit D0: result code (word) SetApplLimit sets the application heap limit, beyond which the application heap can’t be expanded. The actual expansion isn’t under your program’s control, but is done automatically by the Memory Manager when necessary to satisfy allocation requests. Only the original application zone can be expanded. ZoneLimit is a pointer to a byte in memory beyond which the zone will not be allowed to grow. The zone can grow to include the byte preceding zoneLimit in memory, but no farther. If the zone already extends beyond the specified limit it won’t be cut back, but it will be prevented from growing any more. Warning: Notice that zoneLimit is not a byte count. To limit the application zone to a particular size (say 8K bytes), you have to write something like SetApplLimit(Ptr(ApplicZone)+8192) The Memory Manager function ApplicZone is explained below. Assembly-language note: You can just store the new application heap limit in the global variable ApplLimit. Result codes noErr No error memFullErr Not enough room in heap zone æKY SetGrowZone æFp Memory.p æT PROCEDURE æTN $A04B æD PROCEDURE SetGrowZone(growZone: ProcPtr); æDT SetGrowZone(growZone); æRI SetGrowZone procedure II-42 æC Trap macro _SetGrowZone On entry A0: growZone (pointer) On exit D0: result code (word) SetGrowZone sets the current heap zone’s grow zone function as designated by the growZone parameter. A NIL parameter value removes any grow zone function the zone may previously have had. Note: If your program presses the limits of the available heap space, it’s a good idea to have a grow zone function of some sort. At the very least, the grow zone function should take some graceful action—such as displaying an alert box with the message “Out of memory”—instead of just failing unpredictably. If it has failed to create a block of the needed size after compacting the zone, increasing its size (in the case of the original application zone), and purging blocks from it, the Memory Manager calls the grow zone function as a last resort. The grow zone function should be of the form FUNCTION MyGrowZone (cbNeeded: Size) : LONGINT; The cbNeeded parameter gives the physical size of the needed block in bytes, including the block header. The grow zone function should attempt to create a free block of at least this size. It should return a nonzero number if it’s able to allocate some memory, or 0 if it’s not able to allocate any. If the grow zone function returns 0, the Memory Manager will give up trying to allocate the needed block and will signal failure with the result code memFullErr. Otherwise it will compact the heap zone and try again to allocate the block. If still unsuccessful, it will continue to call the grow zone function repeatedly, compacting the zone again after each call, until it either succeeds in allocating the needed block or receives a zero result and gives up. The usual way for the grow zone function to free more space is to call EmptyHandle to purge blocks that were previously marked unpurgeable. Another possibility is to unlock blocks that were previously locked Note: Although just unlocking blocks doesn’t actually free any additional space in the zone, the grow zone function should still return a nonzero result in this case. This signals the Memory Manager to compact the heap and try again to allocate the needed block. Warning: Depending on the circumstances in which the grow zone function is called, there may be a particular block within the heap zone that must not be moved. For this reason, it’s essential that your grow zone function call the function GZSaveHnd (see below). Result codes noErr No error æKY SetHandleSize æFp Memory.p æT PROCEDURE æTN $A024 æD PROCEDURE SetHandleSize(h: Handle;newSize: Size); æDT SetHandleSize(h,newSize); æMM æRI SetHandleSize procedure II-34 æC Trap macro _SetHandleSize On entry A0: h (handle) D0: newSize (long word) On exit D0: result code (word) SetHandleSize changes the logical size of the relocatable block whose handle is h to newSize bytes. Note: Be prepared for an attempt to increase the size of a locked block to fail, since there may be a block above it that’s either nonrelocatable or locked. Result codes noErr No error memFullErr Not enough room in heap zone nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY SetPtrSize æFp Memory.p æT PROCEDURE æTN $A020 æD PROCEDURE SetPtrSize(p: Ptr;newSize: Size); æDT SetPtrSize(p,newSize); æMM æRI SetPtrSize procedure II-37 æC Trap macro _SetPtrSize On entry A0: p (pointer) D0: newSize (long word) On exit D0: result code (word) SetPtrSize changes the logical size of the nonrelocatable block pointed to by p to newSize bytes. Result codes noErr No error memFullErr Not enough room in heap zone memWZErr Attempt to operate on a free block æKY SetZone æFp Memory.p æT PROCEDURE æTN $A01B æD PROCEDURE SetZone(hz: THz); æDT SetZone(hz); æRI SetZone procedure II-31, N8-1 æC Trap macro _SetZone On entry A0: hz (pointer) On exit D0: result code (word) SetZone sets the current heap zone to the zone pointed to by hz. Assembly-language note: You can set the current heap zone by storing a pointer to it in the global variable TheZone. Result codes noErr No error æKY Size æFp Memory.p æT TYPE æC Size = LONGINT; { size of a block in bytes } For specifying the sizes of blocks in the heap, the Memory Manager defines a special type called Size: TYPE Size = LONGINT; All Memory Manager routines that deal with block sizes expect parameters of type Size or return them as results. æKY StackSpace æFp Memory.p æT FUNCTION æTN $A065 æD FUNCTION StackSpace: LONGINT; æDT myVariable := StackSpace; æRI StackSpace function IV-78 æC Trap macro _StackSpace On exit D0: function result (word) StackSpace returns the current amount of stack space between the current stack pointer and the application heap (at the instant of return from the trap). æKY StripAddress æFp Memory.p æT FUNCTION æTN $A055 æD FUNCTION StripAddress(theAddress: Ptr): Ptr; æDT myVariable := StripAddress(theAddress); æRT 212,213 æRI StripAddress function V-593 æC Trap macro _StripAddress On entry D0: theAddress (pointer) On exit D0: function result (pointer) The original description of StripAddress was incorrect. Technical Note #213 correctly documents this function. •••Refer to Technical Note #213:••• æKY SystemZone æFp Memory.p æT FUNCTION æD FUNCTION SystemZone: THz; æDT myVariable := SystemZone; æRI SystemZone function II-32 æC [Not in ROM] SystemZone returns a pointer to the system heap zone. Assembly-language note: The global variable SysZone contains a pointer to the system heap zone. æKY TopMem æFp Memory.p æT FUNCTION æD FUNCTION TopMem: Ptr; æDT myVariable := TopMem; æRI TopMem function II-44 æC [Not in ROM] On a Macintosh 128K or 512K, TopMem returns a pointer to the end of RAM; on the Macintosh XL, it returns a pointer to the end of the memory available for use by the application. Assembly-language note: This value is stored in the global variable MemTop. æKY Menus.p æKL AddResMenu AppendMenu CalcMenuSize CheckItem ClearMenuBar CountMItems DeleteMenu DelMCEntries DelMenuItem DisableItem DispMCInfo DisposeMenu DrawMenuBar EnableItem FlashMenuBar GetItem GetItemCmd GetItemIcon GetItemMark GetItemStyle GetMCEntry GetMCInfo GetMenu GetMenuBar GetMHandle GetNewMBar HiliteMenu InitMenus InitProcMenu InsertMenu InsertResMenu InsMenuItem MenuChoice MenuKey MenuSelect NewMenu PopUpMenuSelect SetItem SetItemCmd SetItemIcon SetItemMark SetItemStyle SetMCEntries SetMCInfo SetMenuBar SetMenuFlash dsHMenuFindErr dsMBarNFnd hierMenu hMenuCmd hPopUpMsg MCEntry MCEntryPtr mChooseMsg MCTable MCTableHandle MCTablePtr mctAllItems mctLastIDIndic mDrawMsg MenuHandle MenuInfo MenuPtr mPopUpMsg mSizeMsg noMark textMenuProc æKY MenuInfo,MenuPtr,MenuHandle æFp Menus.p æT TYPE æC MenuPtr = ^MenuInfo; MenuHandle = ^MenuPtr; MenuInfo = RECORD menuID: INTEGER; menuWidth: INTEGER; menuHeight: INTEGER; menuProc: Handle; enableFlags: LONGINT; menuData: Str255; END; _______________________________________________________________________________ »MENU MANAGER DATA STRUCTURES _______________________________________________________________________________ The Menu Manager keeps all the information it needs for its operations on a particular menu in a menu record. The menu record contains the following: • The menu ID, a number that identifies the menu. The menu ID can be the same number as the menu’s resource ID, though it doesn’t have to be. • The menu title. • The contents of the menu—the text and other parts of each item. • The horizontal and vertical dimensions of the menu, in pixels. The menu items appear inside the rectangle formed by these dimensions; the black border and shadow of the menu appear outside that rectangle. • A handle to the menu definition procedure. • Flags telling whether each menu item is enabled or disabled, and whether the menu itself is enabled or disabled. The data type for a menu record is called MenuInfo. A menu record is referred to by a handle: TYPE MenuPtr = ^MenuInfo; MenuHandle = ^MenuPtr; You can store into and access all the necessary fields of a menu record with Menu Manager routines, so normally you don’t have to know the exact field names. However, if you want more information about the exact structure of a menu record—if you’re defining your own menu types, for instance—it’s given below. _______________________________________________________________________________ »The MenuInfo Data Type The type MenuInfo is defined as follows: TYPE MenuInfo = RECORD menuID: INTEGER; {menu ID} menuWidth: INTEGER; {menu width in pixels} menuHeight: INTEGER; {menu height in pixels} menuProc: Handle; {menu definition procedure} enableFlags: LONGINT; {tells if menu or items are enabled} menuData: Str255 {menu title (and other data)} END; The menuID field contains the menu ID. MenuWidth and menuHeight are the menu’s horizontal and vertical dimensions in pixels. MenuProc is a handle to the menu definition procedure for this type of menu. Bit 0 of the enableFlags field is 1 if the menu is enabled, or 0 if it’s disabled. Bits 1 to 31 similarly tell whether each item in the menu is enabled or disabled. The menuData field contains the menu title followed by variable-length data that defines the text and other parts of the menu items. The Str255 data type enables you to access the title from Pascal; there’s actually additional data beyond the title that’s inaccessible from Pascal and is not reflected in the MenuInfo data structure. Warning: You can read the menu title directly from the menuData field, but do not change the title directly, or the data defining the menu items may be destroyed. The MenuInfo data structure is shown below; this version is similar to what is shown earlier in this section, but includes additional information about menu items. Warning: The MenuInfo data structure is listed for information only; applications should never access it directly. This structure is not a valid Pascal type because of its dynamic size; it’s shown for conceptual purposes only. TYPE MenuInfo = RECORD menuID: INTEGER; {menu ID} menuWidth: INTEGER; {pixels} menuHeight: INTEGER; {pixels} menuProc: Handle; {handle} enableFlags: LONGINT; {bit string} menuTitle: String; {menu title name} itemData: ARRAY [1..X] OF itemString: string; {item name} itemIcon: BYTE; {iconnum-256} itemCmd: char; {item cmd key} itemMark: char; {item mark is a byte} { value for } { hierachical menus} itemStyle: Style; {bit string} endMarker: Byte; {zero-length string } { indicates no more } { menu items} END; Field descriptions menuID The menuID field contains the menu ID of the menu. menuWidth The menuWidth field contains the width in pixels of the menu. menuHeight The menuHeight field contains the height in pixels of the menu. menuProc The menuProc field contains a handle to the menu’s definition procedure. enableFlags The enableFlags field is a bit string which allows the menu and the first 31 items to be enabled or disabled. All items beyond 31 are always enabled. menuTitle The menuTitle field is a string containing the menu title. itemData The itemData field is an array containing the following information for each menu item: item name, item icon number, item command key equivalent, item mark, and item style. For hierarchical menus, the itemMark field is a byte value. endMarker The endMarker field is a byte value, which contains zero if there are no more menu items. The contents of the itemData array are the same for hierarchical and nonhierarchical menus, but for hierarchical menus the itemMark field is a byte value, which limits hierarchical menu menuID values to between 0 and 255. Hierarchical menus numbered 236 to 255 are reserved for use by desk accessories. Desk accessories must remove their hierarchical menus from the MenuList each time their window is not the frontmost, to prevent hierarchical menu collisions with other desk accessories. æKY MCEntry,MCEntryPtr,MCTable,MCTablePtr,MCTableHandle æFp Menus.p æT TYPE æC MCEntryPtr = ^MCEntry; MCTablePtr = ^MCTable; MCTableHandle = ^MCTablePtr; MCTable = ARRAY [0..0] OF MCEntry; { the entries themselves } MCEntry = RECORD mctID: INTEGER; {menu ID. ID = 0 is the menu bar} mctItem: INTEGER; {menu Item. Item = 0 is a title} mctRGB1: RGBColor; {usage depends on ID and Item} mctRGB2: RGBColor; {usage depends on ID and Item} mctRGB3: RGBColor; {usage depends on ID and Item} mctRGB4: RGBColor; {usage depends on ID and Item} mctReserved: INTEGER; {reserved for internal use} END; »Color Menu Data Structures For the Macintosh II, menus can be colored in 2-bit mode or higher, in both color and gray-scale. The menu color information is contained in a table format, but because this format is different from the standard color table format, it is referred to as the menu color information table, rather than the menu color table. A menu color information table is composed of several entries, each of which is an MCEntry record. These data structures are shown below: TYPE MCEntryPtr = ^MCEntry; MCEntry = RECORD mctID: INTEGER; {menu ID. ID = 0 is } { the menu bar} mctItem: INTEGER; {menu entry. Item = 0 } { is a title} mctRGB1: RGBColor; {usage depends on ID and Item} mctRGB2: RGBColor; {usage depends on ID and Item} mctRGB3: RGBColor; {usage depends on ID and Item} mctRGB4: RGBColor; {usage depends on ID and Item} mctReserved: INTEGER; {reserved for internal use} END; MCTable = ARRAY [0..0] of MCEntry; {The menu entries are } { represented in this array} MCTablePtr = ^MCTable; MCTableHandle = ^MCTablePtr; Field descriptions mctID The mctID field contains the menu ID of the menu. A value of mctID = 0 means that this is the menu bar. mctItem The mctItem field contains the menu item. A value of item = 0 means that the item is a menu title. mctRGB1 The mctRGB1 field contains a color value which depends on the mctID and mctItem. See the description in the following section. mctRGB2 The mctRGB2 field contains a color value which depends on the mctID and mctItem. See the description in the following section. mctRGB3 The mctRGB3 field contains a color value which depends on the mctID and mctItem. See the description in the following section. mctRGB4 The mctRGB4 field contains a color value which depends on the mctID and mctItem. See the description in the following section. mctReserved The mctReserved field is used internally; applications must not use this field. The color information table is created at InitMenus time, and its handle is stored in the global variable MenuCInfo ($D50). Like the MenuList data structure, it is only created the first time InitMenus or InitProcMenu is called for an application. A menu color information table is shown in Figure 3. •••Refer to Figure 3.••• Figure 3–Menu Color Information Table There is always at least one entry in the color table, the last entry, which has the arbitrary value –99 in the ID field as an “end-of-table” marker. (This means that the value –99 cannot be used as an ID by an application.) Note that the other fields in the “end-of-table” entry are reserved by use for Apple. Each entry in the color information table has seven fields. The first two fields define the entry’s menu and item. The last field is used internally and has no information for use by programmers. The other fields define colors depending on what type of menu element the entry describes. All colors are specified as RGB colors. There are three types of entries in the menu color information table: one type for the menu bar, one type for menu titles, and one type for menu items. The menu bar entry has ID = 0, Item = 0. There will be at most one menu bar entry in the color information table. If there is no menu bar entry, the default menu bar colors are black text on a white background. The fields in a menu bar entry are as follows: • mctRGB1 is the default color for menu titles. If a menu title doesn’t have an entry in the table, then this is the color used to draw the title. • mctRGB2 is the default color for the background of a pulled down menu. If a menu title doesn’t have an entry in the table, this color is used as the menu’s background color. • mctRGB3 is the default color for the items in a pulled down menu. If a menu item doesn’t have an entry in a table, and if the title for that menu item doesn’t also have an entry, this color will be used to color the mark, name, and Command-key equivalent of the item. • mctRGB4 is the menu bar color. The menu title entry has ID <> 0, Item = 0. There will be at most one title entry for each menu in the color information table. If there is no title entry, the title, menu background, and menu items are drawn using the defaults found in the menu bar entry. If there is no menu bar entry, the default colors are black on white. The fields in a title entry areas follows: • mctRGBG1 is the title color. • mctRGB2 is the menu bar color. This is duplicated here from the menu bar entry to speed menu drawing. • mctRGB3 is the default color for the menu items. If a menu item doesn’t have an entry in the table, this color will be used to color the mark, name, and Command-key equivalent of the item. • mctRGB4 is the menu’s background color. The menu item entry has ID <> 0, Item <> 0. There will be at most one item entry for each menu item in the color information table. If there is no entry for a particular item, the item mark, name, and Command-key equivalent are drawn using the defaults found in the title entry. If there is no title entry, the information in the menu bar entry is used. If there is no menu bar entry, the mark, name, and Command-key equivalent are drawn in black. The fields in an item entry are as follows: • mctRGB1 is the mark color. • mctRGB2 is the name color. • mctRGB3 is the Command-key equivalent. • mctRGB4 is the menu’s background color. It’s duplicated here to speed menu drawing. It’s not possible to specify an icon’s color. Black and white icons are drawn in the item’s name color. Icons may be colored using a 'cicn' resource instead of an 'ICON' resource. When an icon is drawn in a menu, the menu defproc attempts to load the 'cicn' resource first, and if it isn’t found, searches for the 'ICON' resource. See the QuickDraw chapter for more information on color icons. _______________________________________________________________________________ »Menu Color Information Table Resource Format The resource type for a menu color information table is 'mctb'. Once read into memory, this data is transferred into the application’s menu color information table. The resource data format is identical to an MCTable, with the addition of a leading word that contains the number of entries in the resource: TYPE MenuCRsrc = RECORD numEntries: integer; data: array [1..numEntries] of MCEntry; END; The 'mctb' resource is loaded automatically by two routines. InitMenus attempts to load an 'mctb' resource = 0, and if it is successful, adds the colors to the application’s menu color information table. GetMenu attempts to load an 'mctb' resource with the same resource ID as the menu it has loaded, and if it succeeds, it adds the colors to the application’s menu color information table. æKY AddResMenu æFp Menus.p æT PROCEDURE æTN $A94D æD PROCEDURE AddResMenu(theMenu: MenuHandle;theType: ResType); æDT AddResMenu(theMenu,theType); æMM æRT 191, 198 æRI AddResMenu procedure I-353, V-243, P-102 æC AddResMenu searches all open resource files for resources of type theType and appends the names of all resources it finds to the given menu. Each resource name appears in the menu as an enabled item, without an icon or mark, and in the plain character style. The standard Menu Manager calls can be used to get the name or change its appearance, as described in the section “Controlling the Appearance of Items”. Note: If the name of your desk accessory appears not to have been sorted and is inserted at the end of the Apple menu, the name is missing the leading null character. Note: So that you can have resources of the given type that won’t appear in the menu, any resource names that begin with a period (.) or a percent sign (%) aren’t appended by AddResMenu. Use this procedure to fill a menu with the names of all available fonts or desk accessories. For example, if you declare a variable as VAR fontMenu: MenuHandle; you can set up a menu containing all font names as follows: fontMenu := NewMenu(5,'Fonts'); AddResMenu(fontMenu,'FONT') Warning: Before returning, AddResMenu issues the Resource Manager call SetResLoad(TRUE). If your program previously called SetResLoad(FALSE) and you still want that to be in effect after calling AddResMenu, you’ll have to call it again. When AddResMenu or InsertResMenu is called for 'FONT' or 'FOND' resources, special processing occurs for fontNumbers greater than or equal to $4000, as is the case for international fonts. If the script associated with the font is currently active, then the ItemCmd and ItemIcon fields are used to store information allowing the font names to be displayed in the correct script. There is a known problem with the AddResMenu and InsertResMenu routines, and with the menu enable flags, when the number of items is greater than 31. Applications should explicitly reenable or redisable all items after calling AddResMenu or InsertResMenu. This is because only the first 31 items are affected by the enable flags: all items 32 and greater are always enabled. æKY AppendMenu æFp Menus.p æT PROCEDURE æTN $A933 æD PROCEDURE AppendMenu(menu: MenuHandle;data: Str255); æDT AppendMenu(menu,data); æMM æRI AppendMenu procedure I-352, V-243, P-102 æC AppendMenu adds an item or items to the end of the given menu, which must previously have been allocated by NewMenu or read from a resource file by GetMenu. The data string consists of the text of the menu item; it may be blank but should not be the empty string. If it begins with a hyphen (–), the item will be a dividing line across the width of the menu. As described in the section “Creating a Menu in Your Program”, the following meta-characters may be embedded in the data string: Meta-character Usage ; or Return Separates multiple items ^ Followed by an icon number, adds that icon to the item ! Followed by a character, marks the item with that character < Followed by B, I, U, O, or S, sets the character style of the item / Followed by a character, associates a keyboard equivalent with the item ( Disables the item Once items have been appended to a menu, they cannot be removed or rearranged. AppendMenu works properly whether or not the menu is in the menu list. _______________________________________________________________________________ »CREATING A MENU IN YOUR PROGRAM _______________________________________________________________________________ The best way to create your application’s menus is to set them up as resources and read them in from a resource file. If you want your application to create the menus itself, though, it must call the NewMenu and AppendMenu routines. NewMenu creates a new menu data structure, returning a handle to it. AppendMenu takes a string and a handle to a menu and adds the items in the string to the end of the menu. The string passed to AppendMenu consists mainly of the text of the menu items. For a dividing line, use one hyphen (–); AppendMenu ignores any following characters, and draws a dotted line across the width of the menu. For a blank item, use one or more spaces. Other characters interspersed in the string have special meaning to the Menu Manager. These “meta-characters” are used in conjunction with text to separate menu items or alter their appearance (for example, you can use one to disable any dividing line or blank item). The meta-characters aren’t displayed in the menu. Meta-character Meaning ; or Return Separates items ^ Item has an icon ! Item has a check or other mark < Item has a special character style / Item has a keyboard equivalent ( Item is disabled None, any, or all of these meta-characters can appear in the AppendMenu string; they’re described in detail below. To add one text-only item to a menu would require a simple string without any meta-characters: AppendMenu(thisMenu,'Just Enough') An extreme example could use many meta-characters: AppendMenu(thisMenu,'(Too Much^1<B/T') This example adds to the menu an item whose text is “Too Much”, which is disabled, has icon number 1, is boldfaced, and can be invoked by Command-T. Your menu items should be much simpler than this. Note: If you want any of the meta-characters to appear in the text of a menu item, you can include them by changing the text with the Menu Manager procedure SetItem. _______________________________________________________________________________ »Multiple Items Each call to AppendMenu can add one or many items to the menu. To add multiple items in the same call, use a semicolon (;) or a Return character to separate the items. The call AppendMenu(thisMenu,'Cut;Copy') has exactly the same effect as the calls AppendMenu(thisMenu,'Cut'); AppendMenu(thisMenu,'Copy') _______________________________________________________________________________ »Items with Icons A circumflex (^ ) followed by a digit from 1 to 9 indicates that an icon should appear to the left of the text in the menu. The digit, called the icon number, yields the resource ID of the icon in the resource file. Icon resource IDs 257 through 511 are reserved for menu icons; thus the Menu Manager adds 256 to the icon number to get the proper resource ID. Note: The Menu Manager gets the icon number by subtracting 48 from the ASCII code of the character following the “^” (since, for example, the ASCII code of “1” is 49). You can actually follow the “^” with any character that has an ASCII code greater than 48. You can also use the SetItemIcon procedure to install icons in a menu; it accepts any icon number from 1 to 255. _______________________________________________________________________________ »Marked Items You can use an exclamation point (!) to cause a check mark or any other character to be placed to the left of the text (or icon, if any). Follow the exclamation point with the character of your choice; note, however, that normally you can’t type a check mark from the keyboard. To specify a check mark, you need to take special measures: Declare a string variable to have the length of the desired AppendMenu string, and assign it that string with a space following the exclamation point. Then separately store the check mark in the position of the space. For example, suppose you want to use AppendMenu to specify a menu item that has the text “Word Wraparound” (15 characters) and a check mark to its left. You can declare the string variable VAR s: STRING[17]; and do the following: s := '! Word Wraparound'; s[2] := CHR(checkMark); AppendMenu(thisMenu,s) The constant checkMark is defined by the Font Manager as the character code for the check mark. Note: The Font Manager also defines constants for certain other special characters that can’t normally be typed from the keyboard: the apple symbol, the Command key symbol, and a diamond symbol. These symbols can be specified in the same way as the check mark. You can call the SetItemMark or CheckItem procedures to change or clear the mark, and the GetItemMark procedure to find out what mark, if any, is being used. _______________________________________________________________________________ »Character Style of Items The system font is the only font available for menus; however, you can vary the character style of menu items for clarity and distinction. The meta-character for specifying the character style of an item’s text is the less-than symbol (<). With AppendMenu, you can assign one and only one of the stylistic variations listed below. <B Bold <I Italic <U Underline <O Outline <S Shadow The SetItemStyle procedure allows you to assign any combination of stylistic variations to an item. For a further discussion of character style, see the QuickDraw chapter. _______________________________________________________________________________ »Items with Keyboard Equivalents A slash (/) followed by a character associates that character with the item, allowing the item to be invoked from the keyboard with the Command key. The specified character (preceded by the Command key symbol) appears at the right of the item’s text in the menu. Note: Remember to specify the character in uppercase if it’s a letter, and not to specify other shifted characters or numbers. Given a keyboard equivalent typed by the user, you call the MenuKey function to find out which menu item was invoked. _______________________________________________________________________________ »Disabled Items The meta-character that disables an item is the left parenthesis, “(”. A disabled item cannot be chosen; it appears dimmed in the menu and is not highlighted when the cursor moves over it. Menu items that are used to separate groups of items (such as a line or a blank item) should always be disabled. For example, the call AppendMenu(thisMenu,'Undo;(-;Cut') adds two enabled menu items, Undo and Cut, with a disabled item consisting of a line between them. You can change the enabled or disabled state of a menu item with the DisableItem and EnableItem procedures. æKY CalcMenuSize æFp Menus.p æT PROCEDURE æTN $A948 æD PROCEDURE CalcMenuSize(theMenu: MenuHandle); æDT CalcMenuSize(theMenu); æMM æRI CalcMenuSize procedure I-361 æC You can use CalcMenuSize to recalculate the horizontal and vertical dimensions of a menu whose contents have been changed (and store them in the appropriate fields of the menu record). CalcMenuSize is called internally by the Menu Manager after every routine that changes a menu. æKY CheckItem æFp Menus.p æT PROCEDURE æTN $A945 æD PROCEDURE CheckItem(theMenu: MenuHandle;item: INTEGER;checked: BOOLEAN); æDT CheckItem(theMenu,item,checked); æMM æRI CheckItem procedure I-358 æC CheckItem places or removes a check mark at the left of the given menu item. After you call CheckItem with checked=TRUE, a check mark will appear each subsequent time the menu is pulled down. Calling CheckItem with checked=FALSE removes the check mark from the menu item (or, if it’s marked with a different character, removes that mark). Menu items are initially unmarked unless you specify otherwise (such as with the “!” meta-character in a call to AppendMenu). æKY ClearMenuBar æFp Menus.p æT PROCEDURE æTN $A934 æD PROCEDURE ClearMenuBar; æDT ClearMenuBar; æRI ClearMenuBar procedure I-354, V-247 æC Call ClearMenuBar to remove all menus from the menu list when you want to start afresh with all new menus. Be sure to call DrawMenuBar to update the menu bar. Note: ClearMenuBar, like DeleteMenu, doesn’t release the memory occupied by the menu data structures; it merely removes them from the menu list. You don’t have to call ClearMenuBar at the beginning of your program, because InitMenus clears the menu list for you. ClearMenuBar clears both the MenuList and the application’s menu color information table. æKY CountMItems æFp Menus.p æT FUNCTION æTN $A950 æD FUNCTION CountMItems(theMenu: MenuHandle): INTEGER; æDT myVariable := CountMItems(theMenu); æRI CountMItems function I-361 æC CountMItems returns the number of menu items in the given menu. æKY DeleteMenu æFp Menus.p æT PROCEDURE æTN $A936 æD PROCEDURE DeleteMenu(menuID: INTEGER); æDT DeleteMenu(menuID); æRI DeleteMenu procedure I-354, V-244, P-103, 104, 167 æC DeleteMenu deletes a menu from the menu list. If there’s no menu with the given menu ID in the menu list, DeleteMenu has no effect. Be sure to call DrawMenuBar to update the menu bar; the menu titles following the deleted menu will move over to fill the vacancy. Note: DeleteMenu simply removes the menu from the list of currently available menus; it doesn’t release the memory occupied by the menu data structure. The DeleteMenu routine removes all color entries from the menu color information table for the specified menuID. It first checks the hierarchical portion of the MenuList for the menuID and, if it finds it, deletes the menu; it then returns. If the menu is not found in the hierarchical portion of the MenuList, the regular portion is checked. The hierarchical portion of the MenuList is always checked first, so that any desk accessories whose hierarchical menu IDs conflict with an application’s regular menu IDs can call DeleteMenu without deleting the application’s menus. æKY DelMCEntries æFp Menus.p æT PROCEDURE æTN $AA60 æD PROCEDURE DelMCEntries(menuID: INTEGER;menuItem: INTEGER); æDT DelMCEntries(menuID,menuItem); æMM æRI DelMCEntries procedure V-238 æC [Macintosh II] The DelMCEntries routine deletes entries from the menu color information table based on the given menuID and menuItem. If the entry is not found, no entry is removed. If the menuItem is mctAllItems (–98), then all Items for the specified ID are removed. Applications must, of course, never delete the last entry in the menu color information table. æKY DelMenuItem æFp Menus.p æT PROCEDURE æTN $A952 æD PROCEDURE DelMenuItem(theMenu: MenuHandle;item: INTEGER); æDT DelMenuItem(theMenu,item); æMM æRI DelMenuItem procedure IV-56, V-244 æC DelMenuItem removes the item’s color entry from the menu color information table, and then deletes the item. Note: DelMenuItem is intended for maintaining dynamic menus (such as a list of open windows). It should not be used for disabling items; you should use DisableItem instead. æKY DisableItem æFp Menus.p æT PROCEDURE æTN $A93A æD PROCEDURE DisableItem(theMenu: MenuHandle;item: INTEGER); æDT DisableItem(theMenu,item); æRI DisableItem procedure I-358, V-245, P-104, 168 æC Given a menu item number in the item parameter, DisableItem disables that menu item; given 0 in the item parameter, it disables the entire menu. Disabled menu items appear dimmed and are not highlighted when the cursor moves over them. MenuSelect and MenuKey return 0 in the high-order word of their result if the user attempts to invoke a disabled item. Use DisableItem to disable all menu choices that aren’t appropriate at a given time (such as a Cut command when there’s no text selection). All menu items are initially enabled unless you specify otherwise (such as by using the “(” meta- character in a call to AppendMenu). When you disable an entire menu, call DrawMenuBar to update the menu bar. The title of a disabled menu and every item in it are dimmed. The EnableItem and DisableItem routines provide enable flags that can handle the title and 31 menu items. All items greater than 31 will be ignored by these calls and will always be enabled. æKY DispMCInfo æFp Menus.p æT PROCEDURE æTN $AA63 æD PROCEDURE DispMCInfo(menuCTbl: MCTableHandle); æDT DispMCInfo(menuCTbl); æMM æRI DispMCInfo procedure V-239 æC [Macintosh II] Given a handle to a menu color information table, the DispMCInfo routine disposes of the table. No checking is done to determine whether the handle is valid. While this procedure currently only calls DisposHandle, to ensure compatibility with any updates to the color portion of the menu manager, it’s a good idea to use this call. æKY DisposeMenu æFp Menus.p æT PROCEDURE æTN $A932 æD PROCEDURE DisposeMenu(theMenu: MenuHandle); æDT DisposeMenu(theMenu); æMM æRI DisposeMenu procedure I-352, P-103, 168 æC Assembly-language note: The macro you invoke to call DisposeMenu from assembly language is named _DisposMenu. Call DisposeMenu to release the memory occupied by a menu that you allocated with NewMenu. (For menus read from a resource file with GetMenu, use the Resource Manager procedure ReleaseResource instead.) This is useful if you’ve created temporary menus that you no longer need. Warning: Make sure you remove the menu from the menu list (with DeleteMenu) before disposing of it. æKY DrawMenuBar æFp Menus.p æT PROCEDURE æTN $A937 æD PROCEDURE DrawMenuBar; æDT DrawMenuBar; æMM æRI DrawMenuBar procedure I-354, V-244, P-101, 104, 169 æC DrawMenuBar redraws the menu bar according to the menu list, incorporating any changes since the last call to DrawMenuBar. This procedure should always be called after a sequence of InsertMenu or DeleteMenu calls, and after ClearMenuBar, SetMenuBar, or any other routine that changes the menu list. DrawMenuBar now properly highlights the selected menu title, if there is one. If your application program assumed that DrawMenuBar would redraw the menu incorrectly, and called HiliteMenu or FlashMenuBar to compensate, what happens now is that the menu bar is redrawn properly, and the next call to HiliteMenu or FlashMenuBar causes the highlighted title to become unhighlighted. æKY EnableItem æFp Menus.p æT PROCEDURE æTN $A939 æD PROCEDURE EnableItem(theMenu: MenuHandle;item: INTEGER); æDT EnableItem(theMenu,item); æRI EnableItem procedure I-358, V-245, P-104, 170 æC Given a menu item number in the item parameter, EnableItem enables the item (which may have been disabled with the DisableItem procedure, or with the “(” meta-character in the AppendMenu string). Given 0 in the item parameter, EnableItem enables the menu as a whole, but any items that were disabled separately (before the entire menu was disabled) remain so. When you enable an entire menu, call DrawMenuBar to update the menu bar. The item or menu title will no longer appear dimmed and can be chosen like any other enabled item or menu. æKY FlashMenuBar æFp Menus.p æT PROCEDURE æTN $A94C æD PROCEDURE FlashMenuBar(menuID: INTEGER); æDT FlashMenuBar(menuID); æMM æRI FlashMenuBar procedure I-361, V-246 æC If menuID is 0 (or isn’t the ID of any menu in the menu list), FlashMenuBar inverts the entire menu bar; otherwise, it inverts the title of the given menu. You can call FlashMenuBar(0) twice to blink the menu bar. FlashMenuBar(0) still inverts the complete menu bar. Strange colors may result if HiliteMenu, or FlashMenuBar with a nonzero parameter, are called while the menu bar is inverted. FlashMenuBar has been modified so that only one menu may be highlighted at a time (see HiliteMenu). If no menu is currently highlighted, calling FlashMenuBar with a nonzero parameter highlights that menu. If the highlighted menu is different than the one being “flashed”, the previously highlighted menu is first restored to normal, and the new menu is highlighted. æKY GetItem æFp Menus.p æT PROCEDURE æTN $A946 æD PROCEDURE GetItem(theMenu: MenuHandle;item: INTEGER;VAR itemString: Str255); æDT GetItem(theMenu,item,itemString); æRI GetItem procedure I-358, P-104, 172 æC GetItem returns the text of the given menu item in itemString. It doesn’t place any meta-characters in the string. This procedure is useful for getting the name of a menu item that was installed with AddResMenu or InsertResMenu. æKY GetItemCmd æFp Menus.p æT PROCEDURE æTN $A84E æD PROCEDURE GetItemCmd(theMenu: MenuHandle;item: INTEGER;VAR cmdChar: CHAR); æDT GetItemCmd(theMenu,item,cmdChar); æRI GetItemCmd procedure V-240 æC [Macintosh Plus, Macintosh SE, Macintosh II] The GetItemCmd routine may be used to determine whether a menu item has a submenu attached. For a menu item with a submenu, the returned cmdChar will have the value $1B. æKY GetItemIcon æFp Menus.p æT PROCEDURE æTN $A93F æD PROCEDURE GetItemIcon(theMenu: MenuHandle;item: INTEGER;VAR iconNum: Byte); æDT GetItemIcon(theMenu,item,iconNum); æRI GetItemIcon procedure I-360, V-246 æC Assembly-language note: The macro you invoke to call GetItemIcon from assembly language is named _GetItmIcon. GetItemIcon returns the icon number associated with the given menu item, as an integer from 1 to 255, or 0 if the item has not been associated with an icon. The icon number is 256 less than the icon’s resource ID. The GetItemIcon procedure may be used to determine the script number of a font item that is the name of an international script. æKY GetItemMark æFp Menus.p æT PROCEDURE æTN $A943 æD PROCEDURE GetItemMark(theMenu: MenuHandle;item: INTEGER;VAR markChar: CHAR); æDT GetItemMark(theMenu,item,markChar); æRI GetItemMark procedure I-359, V-246 æC Assembly-language note: The macro you invoke to call GetItemMark from assembly language is named _GetItmMark. GetItemMark returns in markChar whatever character the given menu item is marked with, or the predefined constant noMark if no mark is present. The GetItemMark procedure may be used to determine the ID of the hierarchical menu associated with a menu item. æKY GetItemStyle æFp Menus.p æT PROCEDURE æTN $A941 æD PROCEDURE GetItemStyle(theMenu: MenuHandle;item: INTEGER;VAR chStyle: Style); æDT GetItemStyle(theMenu,item,chStyle); æRI GetItemStyle procedure I-360, V-247, N61-1 æC Assembly-language note: The macro you invoke to call GetItemStyle from assembly language is named _GetItmStyle. GetItemStyle returns the character style of the given menu item in chStyle. There is a possible bug in this routine, depending on the interpretation of the address of the VAR parameter chStyle. GetItemStyle assumes that the address on the stack points to a word with chStyle in the low byte. MPW Pascal passes the byte address of chStyle regardless of whether it’s in the high or low byte of a word. Since there has never been a bug report for this “problem”, it is listed here for information only. æKY GetMCEntry æFp Menus.p æT FUNCTION æTN $AA64 æD FUNCTION GetMCEntry(menuID: INTEGER;menuItem: INTEGER): MCEntryPtr; æDT myVariable := GetMCEntry(menuID,menuItem); æRI GetMCEntry function V-239 æC [Macintosh II] The GetMCEntry routine finds the entry of the specified menuID and menuItem in the menu color information table, and returns a pointer into the table. If the entry is not found, a NIL pointer is returned. Note: Entries are not removed from the table. Applications must not remove entries from the table directly; they should always use the procedure DelMCEntries to remove entries. Warning: The menu color information table is relocatable, so the GetMCEntry return value may not be valid across traps that move or purge memory. Applications should make a copy of the record in this case. æKY GetMCInfo æFp Menus.p æT FUNCTION æTN $AA61 æD FUNCTION GetMCInfo: MCTableHandle; æDT myVariable := GetMCInfo; æMM æRI GetMCInfo function V-239 æC [Macintosh II] The GetMCInfo routine creates a copy of the current menu color information table and returns a handle to the copy. It doesn’t affect the current menu color information table. If the copy fails, a NIL handle is returned. æKY GetMenu æFp Menus.p æT FUNCTION æTN $A9BF æD FUNCTION GetMenu(resourceID: INTEGER): MenuHandle; æDT myVariable := GetMenu(resourceID); æMM æRT 78 æRI GetMenu function I-351, V-243, N78-2, P-102, 172 æC Assembly-language note: The macro you invoke to call GetMenu from assembly language is named _GetRMenu. GetMenu returns a menu handle for the menu having the given resource ID. It calls the Resource Manager to read the menu from the resource file into a menu record in memory. GetMenu stores the handle to the menu definition procedure in the menu record, reading the procedure from the resource file into memory if necessary. If the menu or the menu definition procedure can’t be read from the resource file, GetMenu returns NIL. To use the menu, you must call InsertMenu to place it in the menu list and DrawMenuBar to update the menu bar to include the new title. Warning: Call GetMenu only once for a particular menu. If you need the menu handle to a menu that’s already in memory, use the Resource Manager function GetResource. To release the memory occupied by a menu that you read from a resource file with GetMenu, use the Resource Manager procedure ReleaseResource. After loading a 'MENU' resource, GetMenu attempts to load an 'mctb' resource with the same resource ID. If an 'mctb' is loaded, all of the entries are added to the application’s menu color information table by making a call to SetMCEntries. æKY GetMenuBar æFp Menus.p æT FUNCTION æTN $A93B æD FUNCTION GetMenuBar: Handle; æDT myVariable := GetMenuBar; æMM æRI GetMenuBar function I-355, P-172 æC GetMenuBar creates a copy of the current menu list and returns a handle to the copy. You can then add or remove menus from the menu list (with InsertMenu, DeleteMenu, or ClearMenuBar), and later restore the saved menu list with SetMenuBar. To release the memory occupied by the saved menu list, use the Memory Manager procedure DisposHandle. Warning: GetMenuBar doesn’t copy the menus themselves, only a list containing their handles. Do not dispose of any menus that might be in a saved menu list. æKY GetMHandle æFp Menus.p æT FUNCTION æTN $A949 æD FUNCTION GetMHandle(menuID: INTEGER): MenuHandle; æDT myVariable := GetMHandle(menuID); æRI GetMHandle function I-361, V-246 æC Given the menu ID of a menu currently installed in the menu list, GetMHandle returns a handle to that menu; given any other menu ID, it returns NIL. The GetMHandle routine looks for the menu in the hierarchical portion of the MenuList first, and if it isn’t found, looks in the regular portion of the MenuList. The routine has no way to determine whether the returned menu is associated with a menu, pop-up, or hierarchical menu. Presumably the application will contain that information. æKY GetNewMBar æFp Menus.p æT FUNCTION æTN $A9C0 æD FUNCTION GetNewMBar(menuBarID: INTEGER): Handle; æDT myVariable := GetNewMBar(menuBarID); æMM æRI GetNewMBar function I-354, V-247, P-102, 172 æC GetNewMBar creates a menu list as defined by the menu bar resource having the given resource ID, and returns a handle to it. If the resource isn’t already in memory, GetNewMBar reads it into memory from the resource file. If the resource can’t be read, GetNewMBar returns NIL. GetNewMBar calls GetMenu to get each of the individual menus. To make the menu list created by GetNewMBar the current menu list, call SetMenuBar. To release the memory occupied by the menu list, use the Memory Manager procedure DisposHandle. Warning: You don’t have to know the individual menu IDs to use GetNewMBar, but that doesn’t mean you don’t have to know them at all: To do anything further with a particular menu, you have to know its ID or its handle (which you can get by passing the ID to GetMHandle, as described in the section “Miscellaneous Routines”). GetNewMBar begins by calling ClearMenuBar, which clears both the MenuList and the application’s menu color information table. Before returning the Handle to the new MenuList, it restores the previous MenuList. It doesn’t restore the previous menu color information table. If that is desired, the application must use GetMCInfo before calling GetNewMBar, and call SetMCInfo afterwards. æKY HiliteMenu æFp Menus.p æT PROCEDURE æTN $A938 æD PROCEDURE HiliteMenu(menuID: INTEGER); æDT HiliteMenu(menuID); æMM æRI HiliteMenu procedure I-357, V-245 æC HiliteMenu highlights the title of the given menu, or does nothing if the title is already highlighted. Since only one menu title can be highlighted at a time, it unhighlights any previously highlighted menu title. If menuID is 0 (or isn’t the ID of any menu in the menu list), HiliteMenu simply unhighlights whichever menu title is highlighted (if any). After MenuSelect or MenuKey, your application should perform the chosen task and then call HiliteMenu(0) to unhighlight the chosen menu title. Assembly-language note: The global variable TheMenu contains the menu ID of the currently highlighted menu. Previously, highlighting a menu title meant inverting the title rectangle, and dehighlighting it meant reinverting it, so that it returned to normal. With color titles, color inversion is usually aesthetically unacceptable, so there is a need to draw the highlighted menu title. HiliteMenu begins by restoring the bits behind the currently highlighted title (if there is one). It then saves the bits behind the title rectangle, and draws the highlighted title. HiliteMenu(0) dehighlights the currently highlighted menu by restoring the bits behind the title. Note: Because an application can only save the bits behind the menu title, only one menu title can be highlighted at a time. æKY hMenuCmd,hierMenu,hPopUpMsg,mctAllItems,mctLastIDIndic,dsMBarNFnd,dsHMenuFindErr æFp Menus.p æC CONST hMenuCmd = $1B; {itemCmd == $1B ==> hierarchical menu } { attached to this item} hierMenu = –1; {for use as "beforeID" with InsertMenu} hPopUpMsg = 3; {pop-up menu placement, asks the defproc to } { calculate the menu rectangle of the pop-up menu} mctAllItems = –98; {for use as a "menuItem" with DelMCEntries} mctLastIDIndic = -99; {last color table entry has this in ID field} dsMBarNFnd = 85; {SysErr code indicating MBDF not found. Used } { by InitProcMenu and InitMenu} dsHMenuFindErr = 86; {SysErr code indicating recursive } { hierarchical menus defined. Used by MenuKey.} æKY InitMenus æFp Menus.p æT PROCEDURE æTN $A930 æD PROCEDURE InitMenus; æDT InitMenus; æMM æRT 211 æRI InitMenus procedure I-351, V-242, P-101, 107, 175 æC InitMenus initializes the Menu Manager. It allocates space for the menu list (a relocatable block in the heap large enough for the maximum-size menu list), and draws the (empty) menu bar. Call InitMenus once before all other Menu Manager routines. An application should never have to call this procedure more than once; to start afresh with all new menus, use ClearMenuBar. Note: The Window Manager initialization procedure InitWindows has already drawn the empty menu bar; InitMenus redraws it. The InitMenus routine now allocates a dynamic MenuList structure with no menus or hierarchical menus. After allocating the initial MenuList, it attempts to load an 'mctb' resource = 0. If the user has chosen default menu color values, this 'mctb' resource = 0 will exist in the System file. If the 'mctb' is loaded, the information contained in the resource is added to the menu color information table by making a call to SetMCEntries. If there is an 'mctb' resource = 0 among the application’s resources, this will be loaded instead of the default 'mctb' in the System file. æKY InitProcMenu æFp Menus.p æT PROCEDURE æTN $A808 æD PROCEDURE InitProcMenu(resID: INTEGER); æDT InitProcMenu(resID); æMM æRI InitProcMenu procedure V-238 æC [Macintosh Plus, Macintosh SE, Macintosh II] Note: The mbVariant field is contained in the low three bits of the mbResID. The high order 13 bits are used to load the proper 'MBDF'. The InitProcMenu routine is called when an application has a custom menu bar defproc, 'MBDF'. InitProcMenu allocates a new MenuList if it hasn’t already been allocated by a previous call to InitMenus, and the mbResID is stored in the mbResID field in the MenuList (note that InitWindows calls InitMenus, so that it can obtain the menu bar height). The effect of InitProcMenu lasts for the duration of the application only; the next InitMenus call will replace the mbResID field in the MenuList with the default value of zero. This affects applications such as development systems, which use multiple heaps and whose “applications” call InitMenus. Note: Apple reserves mbResID values $000–$100 for its own use. æKY InsertMenu æFp Menus.p æT PROCEDURE æTN $A935 æD PROCEDURE InsertMenu(theMenu: MenuHandle;beforeID: INTEGER); æDT InsertMenu(theMenu,beforeID); æMM æRI InsertMenu procedure I-353, V-244, P-98, 102, 104, 175 æC InsertMenu inserts a menu into the menu list before the menu whose menu ID equals beforeID. If beforeID is 0 (or isn’t the ID of any menu in the menu list), the new menu is added after all others. If the menu is already in the menu list or the menu list is already full, InsertMenu does nothing. Be sure to call DrawMenuBar to update the menu bar. The InsertMenu routine can be used to add a hierarchical menu to the Menulist. If beforeID is equal to –1, the menu is a hierarchical menu. If beforeID is greater than or equal to zero, the menu is a nonhierarchical menu. It isn’t necessary for every menu in the hierarchical menu portion of the MenuList to be currently in use; that is, attached to a menu item. Hierarchical menus that are currently unused, but may be used some time later by the application, may be stored there, and attached to menu items only as needed. You should realize that this can cause problems if the unattached submenus have items with Command-key equivalents, because MenuKey will find these equivalents even though the menu is unattached. æKY InsertResMenu æFp Menus.p æT PROCEDURE æTN $A951 æD PROCEDURE InsertResMenu(theMenu: MenuHandle;theType: ResType;afterItem: INTEGER); æDT InsertResMenu(theMenu,theType,afterItem); æMM æRI InsertResMenu procedure I-353, V-243 æC InsertResMenu is the same as AddResMenu (above) except that it inserts the resource names in the menu where specified by the afterItem parameter: If afterItem is 0, the names are inserted before the first menu item; if it’s the item number of an item in the menu, they’re inserted after that item; if it’s equal to or greater than the last item number, they’re appended to the menu. Note: InsertResMenu inserts the names in the reverse of the order that AddResMenu appends them. For consistency between applications in the appearance of menus, use AddResMenu instead of InsertResMenu if possible. æKY InsMenuItem æFp Menus.p æT PROCEDURE æTN $A826 æD PROCEDURE InsMenuItem(theMenu: MenuHandle;itemString: Str255;afterItem: INTEGER); æDT InsMenuItem(theMenu,itemString,afterItem); æMM æRI InsMenuItem procedure IV-55 æC InsMenuItem inserts an item or items into the given menu where specified by the afterItem parameter. If afterItem is 0, the items are inserted before the first menu item; if it’s the item number of an item in the menu, they’re inserted after that item; if it’s equal to or greater than the last item number, they’re appended to the menu. The contents of itemString are parsed as in the AppendMenu procedure. Multiple items are inserted in the reverse of their order in itemString. æKY mDrawMsg,mChooseMsg,mSizeMsg æFp Menus.p æC _______________________________________________________________________________ »The Menu Definition Procedure The menu definition procedure is usually written in assembly language, but may be written in any high-level language. Assembly-language note: The procedure’s entry point must be at the beginning. You may choose any name you wish for the menu definition procedure. Here’s how you would declare one named MyMenu: PROCEDURE MyMenu (message: INTEGER; theMenu: MenuHandle; VAR menuRect: Rect; hitPt: Point; VAR whichItem: INTEGER); The message parameter identifies the operation to be performed. It has one of the following values: CONST mDrawMsg = 0; {draw the menu} mChooseMsg = 1; {tell which item was chosen and highlight it} mSizeMsg = 2; {calculate the menu's dimensions} The parameter theMenu indicates the menu that the operation will affect. MenuRect is the rectangle (in global coordinates) in which the menu is located; it’s used when the message is mDrawMsg or mChooseMsg. Note: MenuRect is declared as a VAR parameter not because its value is changed, but because of a Pascal feature that will cause an error when that parameter isn’t used. The message mDrawMsg tells the menu definition procedure to draw the menu inside menuRect. The current grafPort will be the Window Manager port. (For details on drawing, see the QuickDraw chapter.) The standard menu definition procedure figures out how to draw the menu items by looking in the menu record at the data that defines them; this data is described in detail under “Formats of Resources for Menus” below. For menus of your own definition, you may set up the data defining the menu items any way you like, or even omit it altogether (in which case all the information necessary to draw the menu would be in the menu definition procedure itself). You should also check the enableFlags field of the menu record to see whether the menu is disabled (or whether any of the menu items are disabled, if you’re using all the flags), and if so, draw it in gray. Note: MenuKey will always search the menuData field of a MenuInfo record for Command-key equivalents until it finds a zero where a standard menu title should be, even if the MenuInfo record is for one of your own 'MDEF' resources. To prevent MenuKey from finding a Command-key equivalent in your MenuInfo record, put a couple of bytes of zeros just after the menu’s title. Warning: Don’t change the font from the system font for menu text. (The Window Manager port uses the system font.) When the menu definition procedure receives the message mChooseMsg, the hitPt parameter is the mouse location (in global coordinates), and the whichItem parameter is the item number of the last item that was chosen from this menu (whichItem is initially set to 0). The procedure should determine whether the mouse location is in an enabled menu item, by checking whether hitPt is inside menuRect, whether the menu is enabled, and whether hitPt is in an enabled menu item: • If the mouse location is in an enabled menu item, unhighlight whichItem and highlight the new item (unless the new item is the same as the whichItem), and return the item number of the new item in whichItem. • If the mouse location isn’t in an enabled item, unhighlight whichItem and return 0. Note: When the Menu Manager needs to make a chosen menu item blink, it repeatedly calls the menu definition procedure with the message mChooseMsg, causing the item to be alternately highlighted and unhighlighted. Finally, the message mSizeMsg tells the menu definition procedure to calculate the horizontal and vertical dimensions of the menu and store them in the menuWidth and menuHeight fields of the menu record. The following section describes changes to the default menu definition procedure ('MDEF' resource 0); some of the information presented in this section is accessible only through assembly language. Note: These features will work with the 64K ROM if the new menu definition procedure is in the system resource file. »Variable Size Fonts Menus are displayed in the system font. Since the system font and font size can now be changed, the menu definition procedure calls the QuickDraw procedure GetFontInfo for the system font to determine the height of menu items »Scrolling Menus The default menu definition procedure allows longer menus by implementing automatic scrolling. If the entire menu cannot be drawn on screen, dragging the cursor below the last displayed item will cause the items in the menu to scroll up. Similarly, if items have been scrolled past the top of the menu, dragging the cursor into the highlighted portion of the menu bar will cause the menu to scroll back down. The maximum number of items that can be drawn on the standard Macintosh screen with this new menu definition function is 19 (instead of 20). Warning: You should not disable any menu items in a menu containing more than 31 items because the enableFlags field of the MenuInfoRec can only handle 31 items. æKY MenuChoice æFp Menus.p æT FUNCTION æTN $AA66 æD FUNCTION MenuChoice: LONGINT; æDT myVariable := MenuChoice; æRI MenuChoice function V-240, P-103, 105, 176 æC [Macintosh II] The MenuChoice routine is called only after the result from MenuSelect is zero. It determines if the mouse-up event that terminated MenuSelect was in a disabled menu item. When the mouse button is released over a disabled item in an application menu, MenuChoice returns a long integer whose high-order word is the menuID of the menu, and whose low-order word is the menu item number for the disabled item “chosen”. If the item number is zero, then the mouse-up event occurred when the mouse was either in the menu title or completely outside the menu; there is no way to distinguish between the two. Note: This information is available on the Macintosh Plus and Macintosh SE by directly querying the long word stored in the global variable MenuDisable ($B54). This feature has been added to MenuChoice to make it possible for applications to provide better help facilities. For example, when the Finder calls MenuChoice, and determines that a user has chosen the disabled menu item “Empty Trash” with the Finder, the application could display a message telling the user that it can’t empty the trash because there is nothing currently in the trash. The new MenuChoice capability is implemented by continual updates of the global variable MenuDisable ($B54) whenever a menu is down. As the mouse moves over each item, MenuDisable is updated to reflect the current menu and item ID. The code that changes the value in MenuDisable resides in the standard menu defproc. The return value is undefined when the menu uses a custom menu defproc, unless the custom defproc also supports this feature. æKY MenuKey æFp Menus.p æT FUNCTION æTN $A93E æD FUNCTION MenuKey(ch: CHAR): LONGINT; æDT myVariable := MenuKey(ch); æMM æRI MenuKey function I-356, V-245, P-105, 176 æC MenuKey maps the given character to the associated menu and item for that character. When you get a key-down event with the Command key held down—or an auto-key event, if the command being invoked is repeatable—call MenuKey with the character that was typed. MenuKey highlights the appropriate menu title, and returns a long integer containing the menu ID in its high-order word and the menu item number in its low-order word, just as MenuSelect does (see Figure 4 above). After performing the chosen task, your application should call HiliteMenu(0) to remove the highlighting from the menu title. If the given character isn’t associated with any enabled menu item currently in the menu list, MenuKey returns 0 in the high-order word of the long integer, and the low-order word is undefined. If the given character invokes a menu item in a menu belonging to a desk accessory, MenuKey (like MenuSelect) passes the menu ID and item number to the Desk Manager procedure SystemMenu for processing, and returns 0 to your application in the high-order word of the result. Note: There should never be more than one item in the menu list with the same keyboard equivalent, but if there is, MenuKey returns the first such item it encounters, scanning the menus from right to left and their items from top to bottom. The MenuKey routine first searches for the given key in the regular portion of the MenuList, and if it doesn’t find it there, searches for the key in the hierarchical portion of the MenuList. If the key is in a hierarchical menu, MenuKey highlights the menu title of the menu that “owns” the hierarchical menu. Ownership in this case means the menu in the menu bar that the user would first encounter on the way to the item with the given Command-key equivalent. Because several levels of hierarchy are possible, this traversal may not always be obvious to the user. As before, after performing the chosen task, your application should call HiliteMenu(0) to remove the highlighting from the menu title. Note: The Command-key codes $1B (Control-[ ) through $1F (Control- _ ) are reserved by Apple Computer to indicate meanings other than Command-key equivalents. These key codes are ignored by MenuKey, and a result of zero is always returned. Applications must never use these codes for their own use. The global variable TheMenu contains the ID of the highlighted menu in the menu bar. If an item from a hierarchical menu is chosen, TheMenu contains the ID of the “owner” menu, not the ID of the hierarchical menu. It’s possible, although undesirable, to define so-called “circular” hierarchical menus. A circular hierarchical menu is one in which a submenu has an “ancestor” that is also one of its “offspring”. If MenuKey detects circular hierarchical menus, a SysError = 86 = #DSHMenuFndErr is generated. æKY MenuSelect æFp Menus.p æT FUNCTION æTN $A93D æD FUNCTION MenuSelect(startPt: Point): LONGINT; æDT myVariable := MenuSelect(startPt); æMM æRI MenuSelect function I-355, V-244, P-36, 103, 105, 176 æC When there’s a mouse-down event in the menu bar, the application should call MenuSelect with startPt equal to the point (in global coordinates) where the mouse button was pressed. MenuSelect keeps control until the mouse button is released, tracking the mouse, pulling down menus as needed, and highlighting enabled menu items under the cursor. When the mouse button is released over an enabled item in an application menu, MenuSelect returns a long integer whose high-order word is the menu ID of the menu, and whose low-order word is the menu item number for the item chosen (see Figure 4). It leaves the selected menu title highlighted. After performing the chosen task, your application should call HiliteMenu(0) to remove the highlighting from the menu title. If no choice is made, MenuSelect returns 0 in the high-order word of the long integer, and the low-order word is undefined. This includes the case where the mouse button is released over a disabled menu item (such as Cut, Copy, Clear, or one of the dividing lines in Figure 4), over any menu title, or outside the menu. In the case of a disabled menu item, an application can still determine which item was chosen. See the description of the MenuChoice routine for further details. If the mouse button is released over an enabled item in a menu belonging to a desk accessory, MenuSelect passes the menu ID and item number to the Desk Manager procedure SystemMenu for processing, and returns 0 to your application in the high-order word of the result. Note: When a menu is pulled down, the bits behind it are stored as a relocatable object in the application heap. If your application has large menus, this can temporarily use up a lot of memory. •••Refer to Figure 4.••• Figure 4–MenuSelect and MenuKey Assembly-language note: If the global variable MBarEnable is nonzero, MenuSelect knows that every menu currently in the menu bar belongs to a desk accessory. (See the Desk Manager chapter for more information.) You can store in the global variables MenuHook and MBarHook the addresses of routines that will be called during MenuSelect. Both variables are initialized to 0 by InitMenus. The routine whose address is in MenuHook (if any) will be called repeatedly (with no parameters) while the mouse button is down. The routine whose address is in MBarHook (if any) will be called after the title of the menu is highlighted and the menu rectangle is calculated, but before the menu is drawn. (The menu rectangle is the rectangle in which the menu will be drawn, in global coordinates.) The routine is passed a pointer to the menu rectangle on the stack. It should normally return 0 in register D0; returning 1 will abort MenuSelect. If the user chooses an item with a submenu, MenuSelect returns zero, meaning that no item was selected. If the user selects an item from a hierarchical menu, the menuID of the hierarchical menu and the menuItem of the item chosen are returned, just as though the item had been in a regular menu. If MenuSelect returns zero, an application may call MenuChoice to determine whether the mouse was released over either a disabled menu item or an item with a submenu. Note: The global variable TheMenu contains the ID of the highlighted menu in the menu bar. If an item from a hierarchical menu is chosen, TheMenu contains the ID of the “owner” menu, not the ID of the hierarchical menu. æKY mPopUpMsg æFp Menus.p æC mPopUpMsg = 3; {menu defProc messages - place yourself} æKY NewMenu æFp Menus.p æT FUNCTION æTN $A931 æD FUNCTION NewMenu(menuID: INTEGER;menuTitle: Str255): MenuHandle; æDT myVariable := NewMenu(menuID,menuTitle); æMM æRI NewMenu function I-351, P-102, 103 æC NewMenu allocates space for a new menu with the given menu ID and title, and returns a handle to it. It sets up the menu to use the standard menu definition procedure. (The menu definition procedure is read into memory if it isn’t already in memory.) The new menu (which is created empty) is not installed in the menu list. To use this menu, you must first call AppendMenu or AddResMenu to fill it with items, InsertMenu to place it in the menu list, and DrawMenuBar to update the menu bar to include the new title. Application menus should always have positive menu IDs. Negative menu IDs are reserved for menus belonging to desk accessories. No menu should ever have a menu ID of 0. If you want to set up the title of the Apple menu from your program instead of reading it in from a resource file, you can use the constant appleMark (defined by the Font Manager as the character code for the apple symbol). For example, you can declare the string variable VAR myTitle: STRING[1]; and do the following: myTitle := ' '; myTitle[1] := CHR(appleMark) To release the memory occupied by a menu that you created with NewMenu, call DisposeMenu. æKY noMark æFp Menus.p æC { Value indicating item has no mark } noMark = 0; æKY PopUpMenuSelect æFp Menus.p æT FUNCTION æTN $A80B æD FUNCTION PopUpMenuSelect(menu: MenuHandle;top: INTEGER;left: INTEGER; popUpItem: INTEGER): LONGINT; æDT myVariable := PopUpMenuSelect(menu,top,left,popUpItem); æMM æRT 156 æRI PopUpMenuSelect function V-241, N156-2 æC [Macintosh Plus, Macintosh SE, Macintosh II] The PopUpMenuSelect routine allows an application to create a pop-up menu anywhere on the screen. This menu may be colored like any other menu, and it may have submenus. The return value is the same as that for MenuSelect, where the low word is the menu item selected, and the high word is the menu ID. Unlike MenuSelect, PopUpMenuSelect doesn’t highlight any of the menus in the menu bar, so HiliteMenu(0) doesn’t have to be called after completing the chosen task. Pop-up menus are typically used for lists of items, for example, fonts. See the Macintosh User Interface Guidelines chapter for a description of how to use pop-up menus in your application. See MenuSelect for information about the return value when the menu chosen is a hierarchical menu. TheMenu is a handle to the menu that you want “popped up”. The PopUpItem is typically the currently selected item, that is, the last item selected, or the first item if nothing was selected. Doing this allows the user to click on a pop-up menu and release again quickly, without changing the item selection by mistake. The parameters Top and Left define where the top left corner of the PopUpItem is to appear, in global coordinates. Typically, these will be the top left coordinates of the pop-up box, so that the menu item appears on top of the pop-up box. See Figure 5 for an example. •••Refer to Figure 5.••• Figure 5–Pop-up Box Parameters »Drawing the Pop-Up Box Your application is responsible for drawing the pop-up box. A pop-up box is a rectangle that is the same height as the menu item, is wide enough to show the currently selected item, and has a one-pixel-wide drop shadow. The pop-up box must be the same height as a menu item so that when the menu appears, the cursor will be in the previously chosen item. If the pop-up box is too tall, the user could click once quickly in a pop-up box and unintentionally choose a different menu item. The height of a menu item in the system font is the ascent + descent + leading. The pop-up box has a title to its left. The application is responsible for recognizing a mouse-down event in the pop-up box, and highlighting the title to the left of the pop-up menu box before calling MenuSelect. Similarly, the application is responsible for highlighting the title if the pop-up menu has Command-key equivalents. Before calling PopUpMenuSelect, the pop-up menu must be installed in the hierarchical portion of the MenuList by passing a value of –1 as the “beforeID” to InsertMenu. The following is a sample psuedocode stub that might be used to track a pop-up menu: if mouse is in popUpMenuRect then myInvertPopUpTitle(); {invert title of pop-up menu} InsertMenu(popupMenuHandle, -1); {-1 means hierarchical menu} Result = PopUpMenuSelect(popUpMenuHandle, popUpRect.Top, popUpRect.Left, lastItemSelected); DeleteMenu(popUpMenuID); myInvertPopUpTitle(); {return pop-up title to normal} endif Notice that PopUpMenuSelect’s sole function is to display the pop-up menu and track the mouse during a mouse-down event. It is the application’s responsibility to handle all other pop-up menu functions, such as drawing the pop-up box, drawing and highlighting the title, and changing the entry in the pop-up box after an item has been chosen from the pop-up menu. This could all be handled by creating a pop-up menu control within the application. When calling PopUpMenuSelect, the pop-up menu must be in the MenuList for the duration of the call. The code above shows a call the InsertMenu before, and a call to DeleteMenu after, the call to PopUpMenuSelect. The InsertMenu must be used at some time before the call to PopUpMenuSelect, but it’s not necessary to call DeleteMenu immediately afterwards; the pop-up menu may be left in the MenuList if desired. Pop-up menu items can have Command-key equivalents. The application must provide sufficient visual feedback, normally provided by using MenuKey, by inverting the pop-up title. æKY SetItem æFp Menus.p æT PROCEDURE æTN $A947 æD PROCEDURE SetItem(theMenu: MenuHandle;item: INTEGER;itemString: Str255); æDT SetItem(theMenu,item,itemString); æMM æRI SetItem procedure I-357, P-104, 180 æC SetItem changes the text of the given menu item to itemString. It doesn’t recognize the meta-characters used in AppendMenu; if you include them in itemString, they will appear in the text of the menu item. The attributes already in effect for this item—its character style, icon, and so on—remain in effect. ItemString may be blank but should not be the empty string. Note: It’s good practice to store the text of itemString in a resource file instead of passing it directly. Use SetItem to change between the two forms of a toggled command—for example, to change “Show Clipboard” to “Hide Clipboard” when the Clipboard is already showing. Note: To avoid confusing the user, don’t capriciously change the text of menu items. æKY SetItemCmd æFp Menus.p æT PROCEDURE æTN $A84F æD PROCEDURE SetItemCmd(theMenu: MenuHandle;item: INTEGER;cmdChar: CHAR); æDT SetItemCmd(theMenu,item,cmdChar); æRI SetItemCmd procedure V-240 æC [Macintosh Plus, Macintosh SE, Macintosh II] The SetItemCmd routine allows the application to attach a submenu to a menu by passing the character $1B. You should be careful about arbitrarily adding or removing a submenu from a menu item; see the Macintosh User Interface Guidelines chapter for recommendations. Notice that SetItemMark can be used to change the ID of the submenu that is associated with the menu item. Note: SetItemCmd must never be used to change the Command-key value of a menu item that doesn’t have a submenu; users must always be free to change their Command-key preferences. æKY SetItemIcon æFp Menus.p æT PROCEDURE æTN $A940 æD PROCEDURE SetItemIcon(theMenu: MenuHandle;item: INTEGER;icon: Byte); æDT SetItemIcon(theMenu,item,icon); æMM æRI SetItemIcon procedure I-359, V-246 æC Assembly-language note: The macro you invoke to call SetItemIcon from assembly language is named _SetItmIcon. SetItemIcon associates the given menu item with an icon. It sets the item’s icon number to the given value (an integer from 1 to 255). The Menu Manager adds 256 to the icon number to get the icon’s resource ID, which it passes to the Resource Manager to get the corresponding icon. Warning: If you call the Resource Manager directly to read or store menu icons, be sure to adjust your icon numbers accordingly. Menu items initially have no icons unless you specify otherwise (such as with the “^” meta-character in a call to AppendMenu). The SetItemIcon procedure should never be called for font items that are international scripts, unless the intention is to change the script number (there should never be any need to do this). æKY SetItemMark æFp Menus.p æT PROCEDURE æTN $A944 æD PROCEDURE SetItemMark(theMenu: MenuHandle;item: INTEGER;markChar: CHAR); æDT SetItemMark(theMenu,item,markChar); æMM æRI SetItemMark procedure I-359, V-246 æC Assembly-language note: The macro you invoke to call SetItemMark from assembly language is named _SetItmMark. SetItemMark marks the given menu item in a more general manner than CheckItem. It allows you to place any character in the system font, not just the check mark, to the left of the item. The character is passed in the markChar parameter. Note: The Font Manager defines constants for the check mark and other special characters that can’t normally be typed from the keyboard: the apple symbol, the Command key symbol, and a diamond symbol. See the Font Manager chapter for more information. To remove an item’s mark, you can pass the following predefined constant in the markChar parameter: CONST noMark = 0; The SetItemMark procedure allows the application to change the submenu associated with a menu item. æKY SetItemStyle æFp Menus.p æT PROCEDURE æTN $A942 æD PROCEDURE SetItemStyle(theMenu: MenuHandle;item: INTEGER;chStyle: Style); æDT SetItemStyle(theMenu,item,chStyle); æMM æRI SetItemStyle procedure I-360 æC Assembly-language note: The macro you invoke to call SetItemStyle from assembly language is named _SetItmStyle. SetItemStyle changes the character style of the given menu item to chStyle. For example: SetItemStyle(thisMenu,1,[bold,italic]) {bold and italic} Menu items are initially in the plain character style unless you specify otherwise (such as with the “<” meta-character in a call to AppendMenu). æKY SetMCEntries æFp Menus.p æT PROCEDURE æTN $AA65 æD PROCEDURE SetMCEntries(numEntries: INTEGER;menuCEntries: MCTablePtr); æDT SetMCEntries(numEntries,menuCEntries); æMM æRI SetMCEntries procedure V-239 æC [Macintosh II] The SetMCEntries procedure takes a pointer to an array of color information records. The array may be of any size, so it’s necessary to also pass the number of entries in the array. The ID and Item of each entry in the color information record array are checked to see if the entry already exists in the menu color information table. If it exists, the information in the entry is used to update the entry in the color table. If the entry doesn’t exist in the color information table, the entry is added to the table. Warning: SetMCEntries makes memory management calls that may move or purge memory; therefore the array menuCEntries should be nonrelocatable for the duration of this call. æKY SetMCInfo æFp Menus.p æT PROCEDURE æTN $AA62 æD PROCEDURE SetMCInfo(menuCTbl: MCTableHandle); æDT SetMCInfo(menuCTbl); æMM æRI SetMCInfo procedure V-239 æC [Macintosh II] The SetMCInfo routine copies the given menu color information table to the current menu color information table. It first disposes of the current menu color information table, so your application shouldn’t explicitly dispose the current table. If the copy fails, the global variable MemErr contains the error code, and the procedure doesn’t dispose the current menu color information table. Applications should call the MemError function to determine if this call failed. You can use this procedure to restore a menu color information table previously saved by GetMCInfo. Be sure to call DrawMenuBar to update the menu bar if a new menu bar color or menu title colors have been specified. æKY SetMenuBar æFp Menus.p æT PROCEDURE æTN $A93C æD PROCEDURE SetMenuBar(menuList: Handle); æDT SetMenuBar(menuList); æRT 180 æRI SetMenuBar procedure I-355, P-102, 180 æC SetMenuBar copies the given menu list to the current menu list. You can use this procedure to restore a menu list previously saved by GetMenuBar, or pass it a handle returned by GetNewMBar. Be sure to call DrawMenuBar to update the menu bar. æKY SetMenuFlash æFp Menus.p æT PROCEDURE æTN $A94A æD PROCEDURE SetMenuFlash(count: INTEGER); æDT SetMenuFlash(count); æRI SetMenuFlash procedure I-361 æC Assembly-language note: The macro you invoke to call SetMenuFlash from assembly language is named _SetMFlash. When the mouse button is released over an enabled menu item, the item blinks briefly to confirm the choice. Normally, your application shouldn’t be concerned with this blinking; the user sets it with the Control Panel desk accessory. If you’re writing a desk accessory like the Control Panel, though, SetMenuFlash allows you to control the duration of the blinking. The count parameter is the number of times menu items will blink; it’s initially 3 if the user hasn’t changed it. A count of 0 disables blinking. Values greater than 3 can be annoyingly slow. Note: Items in both standard and nonstandard menus blink when chosen. The appearance of the blinking for a nonstandard menu depends on the menu definition procedure, as described in “Defining Your Own Menus”. Assembly-language note: The current count is stored in the global variable MenuFlash. æKY textMenuProc æFp Menus.p æC { Resource ID of standard menu definition procedure } textMenuProc = 0; æKY Notification.p æKL NMInstall NMRemove NMRec nmType æKY NMInstall æFp Notification.p æT FUNCTION æTN $A05E æD FUNCTION NMInstall(nmReqPtr: QElemPtr): OSErr; æDT myVariable := NMInstall(nmReqPtr); æRT 184 æKY NMRec æFp Notification.p æT RECORD æC NMRec = RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type -- ORD(nmType) = 8} nmFlags: INTEGER; {reserved} nmPrivate: LONGINT; {reserved} nmReserved: INTEGER; {reserved} nmMark: INTEGER; {item to mark in Apple menu} nmSIcon: Handle; {handle to small icon} nmSound: Handle; {handle to sound record} nmStr: StringPtr; {string to appear in alert} nmResp: ProcPtr; {pointer to response routine} nmRefCon: LONGINT; {for application use} END; æKY NMRemove æFp Notification.p æT FUNCTION æTN $A05F æD FUNCTION NMRemove(nmReqPtr: QElemPtr): OSErr; æDT myVariable := NMRemove(nmReqPtr); æRT 184 æKY nmType æFp Notification.p æC nmType = 8; æKY OSEvents.p æKL FlushEvents GetEvQHdr GetOSEvent OSEventAvail PostEvent PPostEvent SetEventMask æKY FlushEvents æFp OSEvents.p æT PROCEDURE æTN $A032 æD PROCEDURE FlushEvents(whichMask: INTEGER;stopMask: INTEGER); æDT FlushEvents(whichMask,stopMask); æRI FlushEvents procedure II-69, P-31, 170 æC Trap macro _FlushEvents On entry D0: low-order word: eventMask high-order word: stopMask On exit D0: 0 or event code (word) FlushEvents removes events from the event queue as specified by the given event masks. It removes all events of the type or types specified by eventMask, up to but not including the first event of any type specified by stopMask; if the event queue doesn’t contain any events of the types specified by eventMask, it does nothing. To remove all events specified by eventMask, use a stopMask value of 0. At the beginning of your application, it’s usually a good idea to call FlushEvents(everyEvent,0) to empty the event queue of any stray events that may have been left lying around, such as unprocessed keystrokes typed to the Finder. Assembly-language note: On exit from this routine, D0 contains 0 if all events were removed from the queue or, if not, an event code specifying the type of event that caused the removal process to stop. æKY GetEvQHdr æFp OSEvents.p æT FUNCTION æD FUNCTION GetEvQHdr: QHdrPtr; æDT myVariable := GetEvQHdr; æRI GetEvQHdr function II-71 æC [Not in ROM] GetEvQHdr returns a pointer to the header of the event queue. Assembly-language note: The global variable EventQueue contains the header of the event queue. æKY GetOSEvent æFp OSEvents.p æT FUNCTION æTN $A031 æD FUNCTION GetOSEvent(mask: INTEGER;VAR theEvent: EventRecord): BOOLEAN; æDT myVariable := GetOSEvent(mask,theEvent); æRT 85 æRI GetOSEvent function II-69, N85-1 æC Trap macro _GetOSEvent On entry A0: pointer to event record theEvent D0: eventMask (word) On exit D0: 0 if non-null event returned, or –1 if null event returned (byte) GetOSEvent returns the next available event of a specified type or types and removes it from the event queue. The event is returned as the value of the parameter theEvent. The eventMask parameter specifies which event types are of interest. GetOSEvent will return the next available event of any type designated by the mask. If no event of any of the designated types is available, GetOSEvent returns a null event and a function result of FALSE; otherwise it returns TRUE. Note: Unlike the Toolbox Event Manager function GetNextEvent, GetOSEvent doesn’t call the Desk Manager to see whether the system wants to intercept and respond to the event; nor does it perform GetNextEvent’s processing of the alarm and Command-Shift-number combinations. æKY OSEventAvail æFp OSEvents.p æT FUNCTION æTN $A030 æD FUNCTION OSEventAvail(mask: INTEGER;VAR theEvent: EventRecord): BOOLEAN; æDT myVariable := OSEventAvail(mask,theEvent); æRI OSEventAvail function II-70 æC Trap macro _OSEventAvail On entry A0: pointer to event record theEvent D0: eventMask (word) On exit D0: 0 if non-null event returned, or –1 if null event returned (byte) OSEventAvail works exactly the same as GetOSEvent (above) except that it doesn’t remove the event from the event queue. Note: An event returned by OSEventAvail will not be accessible later if in the meantime the queue becomes full and the event is discarded from it; since the events discarded are always the oldest ones in the queue, however, this will happen only in an unusually busy environment. æKY PostEvent æFp OSEvents.p æT FUNCTION æTN $A02F æD FUNCTION PostEvent(eventNum: INTEGER;eventMsg: LONGINT): OSErr; æDT myVariable := PostEvent(eventNum,eventMsg); æRI PostEvent function II-68 æC Trap macro _PostEvent On entry A0: eventCode (word) D0: eventMsg (long word) On exit D0: result code (word) PostEvent places in the event queue an event of the type designated by eventCode, with the event message specified by eventMsg and with the current time, mouse location, and state of the modifier keys and mouse button. It returns a result code (of type OSErr, defined as INTEGER in the Operating System Utilities) equal to one of the following predefined constants: CONST noErr = 0; {no error (event posted)} evtNotEnb = 1; {event type not designated in system event mask} Warning: Be very careful when posting any events other than your own application-defined events into the queue; attempting to post an activate or update event, for example, will interfere with the internal operation of the Toolbox Event Manager, since such events aren’t normally placed in the queue at all. Warning: If you use PostEvent to repost an event, remember that the event time, location, and state of the modifier keys and mouse button will all be changed from their values when the event was originally posted, possibly altering the meaning of the event. æKY PPostEvent æFp OSEvents.p æT FUNCTION æTN $A12F æD FUNCTION PPostEvent(eventCode: INTEGER;eventMsg: LONGINT;VAR qEl: EvQElPtr): OSErr; æDT myVariable := PPostEvent(eventCode,eventMsg,qEl); æC Trap macro _PPostEvent On entry A0: eventCode (word) D0: eventMsg (long word) On exit A0: pointer to event queue entry PPostEvent is identical to PostEvent except that it returns a pointer to the created queue entry. æKY SetEventMask æFp OSEvents.p æT PROCEDURE æD PROCEDURE SetEventMask(theMask: INTEGER); æDT SetEventMask(theMask); æRT 202 æRI SetEventMask procedure II-70 æC [Not in ROM] SetEventMask sets the system event mask to the specified event mask. The Operating System Event Manager will post only those event types that correspond to bits set in the mask. (As usual, it will not post activate and update events, which are generated by the Window Manager and not stored in the event queue.) The system event mask is initially set to post all except key-up events. Warning: Because desk accessories may rely on receiving certain types of events, your application shouldn’t set the system event mask to prevent any additional types (besides key-up) from being posted. You should use SetEventMask only to enable key-up events in the unusual case that your application needs to respond to them. Assembly-language note: The system event mask is available to assembly- language programmers in the global variable SysEvtMask. æKY OSUtils.p æKL Date2Secs Delay Dequeue DTInstall Enqueue Environs EqualString FlushDataCache FlushInstructionCache GetDateTime GetMMUMode GetSysPPtr GetTime GetTrapAddress HandAndHand HandToHand InitUtil KeyTrans NGetTrapAddress NSetTrapAddress PtrAndHand PtrToHand PtrToXHand ReadDateTime RelString Restart RestoreA5 Secs2Date SetA5 SetCurrentA5 SetDateTime SetTime SetTrapAddress SetUpA5 SwapDataCache SwapInstructionCache SwapMMUMode SysBeep SysEnvirons UprString WriteParam curSysEnvVers DateTimeRec DrvQEl DrvQElPtr drvQType dummyType env512KE env68000 env68010 env68020 env68030 envAExtendKbd envCPUUnknown envMac envMacAndPad envMachUnknown envMacKbd envMacPlus envMacPlusKbd envSE envSE30 envStandADBKbd envUnknownKbd envXL EvQEl EvQElPtr evType false32b fsQType ioQType macMachine macXLMachine OSTrap ParamBlockRec ParmBlkPtr QElem QElemPtr QHdr QHdrPtr QTypes sortsAfter sortsBefore sortsEqual SysEnvRec SysParmType SysPPtr ToolTrap TrapType true32b useAsync useATalk useExtClk useFree useMIDI vType æKY ParmBlkPtr,ParamBlockRec æFp OSUtils.p æT TYPE æC ParmBlkPtr = ^ParamBlockRec; ParamBlockRec = RECORD qLink: QElemPtr; qType: INTEGER; ioTrap: INTEGER; ioCmdAddr: Ptr; ioCompletion: ProcPtr; ioResult: OSErr; ioNamePtr: StringPtr; ioVRefNum: INTEGER; CASE ParamBlkType OF IOParam: (ioRefNum: INTEGER; ioVersNum: SignedByte; ioPermssn: SignedByte; ioMisc: Ptr; ioBuffer: Ptr; ioReqCount: LONGINT; ioActCount: LONGINT; ioPosMode: INTEGER; ioPosOffset: LONGINT); FileParam: (ioFRefNum: INTEGER; ioFVersNum: SignedByte; filler1: SignedByte; ioFDirIndex: INTEGER; ioFlAttrib: SignedByte; ioFlVersNum: SignedByte; ioFlFndrInfo: FInfo; ioFlNum: LONGINT; ioFlStBlk: INTEGER; ioFlLgLen: LONGINT; ioFlPyLen: LONGINT; ioFlRStBlk: INTEGER; ioFlRLgLen: LONGINT; ioFlRPyLen: LONGINT; ioFlCrDat: LONGINT; ioFlMdDat: LONGINT); VolumeParam: (filler2: LONGINT; ioVolIndex: INTEGER; ioVCrDate: LONGINT; ioVLsBkUp: LONGINT; ioVAtrb: INTEGER; ioVNmFls: INTEGER; ioVDirSt: INTEGER; ioVBlLn: INTEGER; ioVNmAlBlks: INTEGER; ioVAlBlkSiz: LONGINT; ioVClpSiz: LONGINT; ioAlBlSt: INTEGER; ioVNxtFNum: LONGINT; ioVFrBlk: INTEGER); CntrlParam: (ioCRefNum: INTEGER; csCode: INTEGER; csParam: ARRAY [0..10] OF INTEGER); SlotDevParam: (filler3: LONGINT; ioMix: Ptr; ioFlags: INTEGER; ioSlot: SignedByte; ioID: SignedByte); MultiDevParam: (filler4: LONGINT; ioMMix: Ptr; ioMFlags: INTEGER; ioSEBlkPtr: Ptr); END; æKY DrvQEl,DrvQElPtr æFp OSUtils.p æT TYPE æC DrvQElPtr = ^DrvQEl; DrvQEl = RECORD qLink: QElemPtr; qType: INTEGER; dQDrive: INTEGER; dQRefNum: INTEGER; dQFSID: INTEGER; dQDrvSz: INTEGER; dQDrvSz2: INTEGER; END; »The Drive Queue •••Refer to Technical Note #36:••• Disk drives connected to the Macintosh are opened when the system starts up, and information describing each is placed in the drive queue. This is a standard Operating System queue, and each entry in it has the following structure: TYPE DrvQEl = RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} dQDrive: INTEGER; {drive number} dQRefNum: INTEGER; {driver reference number} dQFSID: INTEGER; {file-system identifier} dQDrvSz: INTEGER; {number of logical blocks on drive} dQDrvSz2: INTEGER; {additional field to handle large } { drive size} END; QLink points to the next entry in the queue. If qType is 0, this means the number of logical blocks on the drive is contained in the dQDrvSz field alone. If qType is 1, both dQDrvSz and dQDrvSz2 are used to store the number of blocks; dqDrvSz2 contains the high-order word of this number and dQDrvSz contains the low-order word. DQDrive contains the drive number of the drive on which the volume is mounted; dQRefNum contains the driver reference number of the driver controlling the device on which the volume is mounted. DQFSID identifies the file system handling the volume in the drive; it’s 0 for volumes handled by the File Manager, and nonzero for volumes handled by other file systems. Four bytes of flags precede each drive queue entry; they’re accessible only from assembly language. Assembly-language note: These bytes contain the following: Byte Contents 0 Bit 7=1 if volume is locked 1 0 if no disk in drive; 1 or 2 if disk in drive; 8 if nonejectable disk in drive; $FC-$FF if disk was ejected within last 1.5 seconds; $48 if disk in drive is nonejectable but driver wants a call 2 Used internally during system startup 3 Bit 7=0 if disk is single-sided You can get a pointer to the header of the drive queue by calling the File Manager function GetDrvQHdr. æKY EvQEl,EvQElPtr æFp OSUtils.p æT TYPE æC EvQElPtr = ^EvQEl; EvQEl = RECORD qLink: QElemPtr; qType: INTEGER; evtQWhat: INTEGER; {this part is identical to the EventRecord as...} evtQMessage: LONGINT; {defined in ToolIntf} evtQWhen: LONGINT; evtQWhere: Point; evtQModifiers: INTEGER; END; »STRUCTURE OF THE EVENT QUEUE _______________________________________________________________________________ The event queue is a standard Macintosh Operating System queue, as described in the Operating System Utilities chapter. Most programmers will never need to access the event queue directly; some advanced programmers, though, may need to do so for special purposes. Each entry in the event queue contains information about an event: TYPE EvQEl = RECORD qLink: QElemPtr; {next queue entry} qType: INTEGER; {queue type} evtQWhat: INTEGER; {event code} evtQMessage: LONGINT; {event message} evtQWhen: LONGINT; {ticks since startup} evtQWhere: Point; {mouse location} evtQModifiers: INTEGER {modifier flags} END; QLink points to the next entry in the queue, and qType indicates the queue type, which must be ORD(evType). The remaining five fields of the event queue entry contain exactly the same information about the event as do the fields of the event record for that event; see the Toolbox Event Manager chapter for a detailed description of the contents of these fields. You can get a pointer to the header of the event queue by calling the Operating System Event Manager function GetEvQHdr. æKY QElem,QElemPtr æFp OSUtils.p æT TYPE æC QElemPtr = ^QElem; QElem = RECORD CASE QTypes OF vType: (vblQElem: VBLTask); {vertical blanking} ioQType: (ioQElem: ParamBlockRec); {I/O parameter block} drvQType: (drvQElem: DrvQEl); {drive} evType: (evQElem: EvQEl); {event} fsQType: (vcbQElem: VCB); {volume control block} END; _______________________________________________________________________________ »OPERATING SYSTEM QUEUES _______________________________________________________________________________ Some of the information used by the Operating System is stored in data structures called queues. A queue is a list of identically structured entries linked together by pointers. Queues are used to keep track of VBL tasks, I/O requests, events, mounted volumes, and disk drives (or other block-formatted devices). A standard Operating System queue has a header with the following structure: TYPE QHdr = RECORD qFlags: INTEGER; {queue flags} qHead: QElemPtr; {first queue entry} qTail: QElemPtr {last queue entry} END; QHdrPtr = ^QHdr; QFlags contains information (usually flags) that’s different for each queue type. QHead points to the first entry in the queue, and qTail points to the last entry in the queue. The entries within each type of queue are different; the Operating System uses the following variant record to access them: TYPE QTypes = (dummyType, vType, {vertical retrace queue type} ioQType, {file I/O or driver I/O queue type} drvQType, {drive queue type} evType, {event queue type} fsQType); {volume-control-block queue type} QElem = RECORD CASE QTypes OF vType: (vblQElem: VBLTask); ioQType: (ioQElem: ParamBlockRec); drvQType: (drvQElem: DrvQEl); evType: (evQElem: EvQEl); fsQType: (vcbQElem: VCB) END; QElemPtr = ^QElem; All entries in queues, regardless of the queue type, begin with four bytes of flags followed by a pointer to the next queue entry. The entries are linked through these pointers; each one points to the pointer field in the next entry. In Pascal, the data type of the pointer is QElemPtr, and the data type of the entry begins with the pointer field. Consequently, the flag bytes are inaccessible from Pascal. Following the pointer to the next entry, each entry contains an integer designating the queue type (for example, ORD(evType) for the event queue). The exact structure of the rest of the entry depends on the type of queue; for more information, see the chapter that discusses that queue in detail. æKY QHdr,QHdrPtr æFp OSUtils.p æT TYPE æC QHdrPtr = ^QHdr; QHdr = RECORD qFlags: INTEGER; qHead: QElemPtr; qTail: QElemPtr; END; _______________________________________________________________________________ »OPERATING SYSTEM QUEUES _______________________________________________________________________________ Some of the information used by the Operating System is stored in data structures called queues. A queue is a list of identically structured entries linked together by pointers. Queues are used to keep track of VBL tasks, I/O requests, events, mounted volumes, and disk drives (or other block-formatted devices). A standard Operating System queue has a header with the following structure: TYPE QHdr = RECORD qFlags: INTEGER; {queue flags} qHead: QElemPtr; {first queue entry} qTail: QElemPtr {last queue entry} END; QHdrPtr = ^QHdr; QFlags contains information (usually flags) that’s different for each queue type. QHead points to the first entry in the queue, and qTail points to the last entry in the queue. The entries within each type of queue are different; the Operating System uses the following variant record to access them: TYPE QTypes = (dummyType, vType, {vertical retrace queue type} ioQType, {file I/O or driver I/O queue type} drvQType, {drive queue type} evType, {event queue type} fsQType); {volume-control-block queue type} QElem = RECORD CASE QTypes OF vType: (vblQElem: VBLTask); ioQType: (ioQElem: ParamBlockRec); drvQType: (drvQElem: DrvQEl); evType: (evQElem: EvQEl); fsQType: (vcbQElem: VCB) END; QElemPtr = ^QElem; All entries in queues, regardless of the queue type, begin with four bytes of flags followed by a pointer to the next queue entry. The entries are linked through these pointers; each one points to the pointer field in the next entry. In Pascal, the data type of the pointer is QElemPtr, and the data type of the entry begins with the pointer field. Consequently, the flag bytes are inaccessible from Pascal. Following the pointer to the next entry, each entry contains an integer designating the queue type (for example, ORD(evType) for the event queue). The exact structure of the rest of the entry depends on the type of queue; for more information, see the chapter that discusses that queue in detail. æKY SysParmType,SysPPtr æFp OSUtils.p æT TYPE æC SysPPtr = ^SysParmType; SysParmType = PACKED RECORD valid: Byte; aTalkA: Byte; aTalkB: Byte; config: Byte; portA: INTEGER; portB: INTEGER; alarm: LONGINT; font: INTEGER; kbdPrint: INTEGER; volClik: INTEGER; misc: INTEGER; END; _______________________________________________________________________________ »PARAMETER RAM _______________________________________________________________________________ Various settings, such as those specified by the user by means of the Control Panel desk accessory, need to be preserved when the Macintosh is off so they will still be present at the next system startup. This information is kept in parameter RAM, 20 bytes that are stored in the clock chip together with the current date and time setting. The clock chip is powered by a battery when the system is off, thereby preserving all the settings stored in it. You may find it necessary to read the values in parameter RAM or even change them (for example, if you create a desk accessory like the Control Panel). Since the clock chip itself is difficult to access, its contents are copied into low memory at system startup. You read and change parameter RAM through this low-memory copy. Note: Certain values from parameter RAM are used so frequently that special routines have been designed to return them (for example, the Toolbox Event Manager function GetDblTime). These routines are discussed in other chapters where appropriate. Assembly-language note: The low-memory copy of parameter RAM begins at the address SysParam; the various portions of the copy can be accessed through individual global variables, listed in the summary at the end of this chapter. Some of these are copied into other global variables at system startup for even easier access; for example, the auto-key threshold and rate, which are contained in the variable SPKbd in the copy of parameter RAM, are copied into the variables KeyThresh and KeyRepThresh. Each such variable is discussed in the appropriate chapter. The date and time setting is also copied at system startup from the clock chip into its own low-memory location. It’s stored as a number of seconds since midnight, January 1, 1904, and is updated every second. The maximum value, $FFFFFFFF, corresponds to 6:28:15 AM, February 6, 2040; after that, it wraps around to midnight, January 1, 1904. Assembly-language note: The low-memory location containing the date and time is the global variable Time. The structure of parameter RAM is represented by the following data type: TYPE SysParmType = RECORD valid: Byte; {validity status} aTalkA: Byte; {AppleTalk node ID hint for modem } { port} aTalkB: Byte; {AppleTalk node ID hint for printer } { port} config: Byte; {use types for serial ports} portA: INTEGER; {modem port configuration} portB: INTEGER; {printer port configuration} alarm: LONGINT; {alarm setting} font: INTEGER; {application font number minus 1} kbdPrint: INTEGER; {auto-key settings, printer } { connection} volClik: INTEGER; {speaker volume, double-click, } { caret blink} misc: INTEGER {mouse scaling, startup disk, } { menu blink} END; SysPPtr = ^SysParmType; The valid field contains the validity status of the clock chip: Whenever you successfully write to the clock chip, $A8 is stored in this byte. The validity status is examined when the clock chip is read at system startup. It won’t be $A8 if a hardware problem prevented the values from being written; in this case, the low-memory copy of parameter RAM is set to the default values shown in the table below, and these values are then written to the clock chip itself. (The meanings of the parameters are explained below in the descriptions of the various fields.) Parameter Default value Validity status $A8 Node ID hint for modem port 0 Node ID hint for printer port 0 Use types for serial ports 0 (both ports) Modem port configuration 9600 baud, 8 data bits, 2 stop bits, no parity Printer port configuration Same as for modem port Alarm setting 0 (midnight, January 1, 1904) Application font number minus 1 2 (Geneva) Auto-key threshold 6 (24 ticks) Auto-key rate 3 (6 ticks) Printer connection 0 (printer port) Speaker volume 3 (medium) Double-click time 8 (32 ticks) Caret-blink time 8 (32 ticks) Mouse scaling 1 (on) Preferred system startup disk 0 (internal drive) Menu blink 3 Warning: Your program must not use bits indicated below as “reserved for future use” in parameter RAM, since future Macintosh software features will use them. The aTalkA and aTalkB fields are used by the AppleTalk Manager; they’re described in the manual Inside AppleTalk. The config field indicates which device or devices may use each of the serial ports; for details, see the section “Calling the AppleTalk Manager from Assembly Language” in the AppleTalk Manager chapter. The portA and portB fields contain the baud rates, data bits, stop bits, and parity for the device drivers using the modem port (“port A”) and printer port (“port B”). An explanation of these terms and the exact format of the information are given in the Serial Drivers chapter. The alarm field contains the alarm setting in seconds since midnight, January 1, 1904. The font field contains 1 less than the number of the application font. See the Font Manager chapter for a list of font numbers. Bit 0 of the kbdPrint field (Figure 1) designates whether the printer (if any) is connected to the printer port (0) or the modem port (1). Bits 8-11 of this field contain the auto-key rate, the rate of the repeat when a character key is held down; this value is stored in two-tick units. Bits 12-15 contain the auto-key threshold, the length of time the key must be held down before it begins to repeat; it’s stored in four-tick units. •••Refer to Figure 1.••• Figure 1–The KbdPrint Field Bits 0-3 of the volClik field (Figure 2) contain the caret-blink time, and bits 4-7 contain the double-click time; both values are stored in four-tick units. The caret-blink time is the interval between blinks of the caret that marks the insertion point in text. The double-click time is the greatest interval between a mouse-up and mouse-down event that would qualify two mouse clicks as a double-click. Bits 8-10 of the volClik field contain the speaker volume setting, which ranges from silent (0) to loud (7). Note: The Sound Driver procedure SetSoundVol changes the speaker volume without changing the setting in parameter RAM, so it’s possible for the actual volume to be different from this setting. Bits 2 and 3 of the misc field (Figure 3) contain a value from 0 to 3 designating how many times a menu item will blink when it’s chosen. Bit 4 of this field indicates whether the preferred disk to use to start up the system is in the internal (0) or the external (1) drive; if there’s any problem using the disk in the specified drive, the other drive will be used. •••Refer to Figure 2.••• Figure 2–The VolClik Field •••Refer to Figure 3.••• Figure 3–The Misc Field Finally, bit 6 of the misc field designates whether mouse scaling is on (1) or off (0). If mouse scaling is on, the system looks every sixtieth of a second at whether the mouse has moved; if in that time the sum of the mouse’s horizontal and vertical changes in position is greater than the mouse-scaling threshold (normally six pixels), then the cursor will move twice as far horizontally and vertically as it would if mouse scaling were off. Assembly-language note: The mouse-scaling threshold is contained in the global variable CrsrThresh. æKY RestoreA5 æFp OSUtils.p æT PROCEDURE æD PROCEDURE RestoreA5; æDT RestoreA5; æRT 136, 208 æRI RestoreA5 procedure II-386, N136 æC Call RestoreA5 at the conclusion of a routine or task that required a call to SetUpA5 (above); it restores register A5 to whatever its value was when SetUpA5 was called. æKY SetA5 æFp OSUtils.p æT FUNCTION æD FUNCTION SetA5(newA5: LONGINT): LONGINT; æDT myVariable := SetA5(newA5); æRT 208 æKY SetUpA5 æFp OSUtils.p æT PROCEDURE æD PROCEDURE SetUpA5; æDT SetUpA5; æRT 136,208 æRI SetUpA5 procedure II-386, N136 æC SetUpA5 saves the current value of register A5 (for restoring later with RestoreA5, described below) and then resets A5 to point to the boundary between the application globals and the application parameters. This procedure is useful only within the interrupt environment, where the state of A5 is unpredictable; for instance, in a completion routine or a VBL task, calling SetUpA5 will ensure that A5 contains the proper value, allowing the routine or task to access the application globals. ________________________________________________________________________ Assembly-language note: You can get the boundary between the application globals and the application parameters from the global variable CurrentA5. ________________________________________________________________________ æKY curSysEnvVers æFp OSUtils.p æC curSysEnvVers = 1; {Updated to equal latest SysEnvirons version} æKY Date2Secs æFp OSUtils.p æT PROCEDURE æTN $A9C7 æD PROCEDURE Date2Secs(d: DateTimeRec;VAR s: LONGINT); æDT Date2Secs(d,s); æRI Date2Secs procedure II-379 æC Trap macro _Date2Secs On entry A0: pointer to date/time record On exit D0: secs (long word) Date2Secs takes the given date/time record, converts it to the corresponding number of seconds elapsed since midnight, January 1, 1904, and returns the result in the secs parameter. The dayOfWeek field of the date/time record is ignored. The values passed in the year and month fields should be within their allowable ranges, or unpredictable results will occur. The remaining four fields of the date/time record may contain any value. For example, September 34 will be interpreted as October 4, and you could specify the 300th day of the year as January 300. æKY DateTimeRec æFp OSUtils.p æT RECORD æC DateTimeRec = RECORD year: INTEGER; month: INTEGER; day: INTEGER; hour: INTEGER; minute: INTEGER; second: INTEGER; dayOfWeek: INTEGER; END; The following utilities are for reading and setting the date and time stored in the clock chip. Reading the date and time is a fairly common operation; setting it is somewhat rarer, but could be necessary for implementing a desk accessory like the Control Panel. The date and time setting is stored as an unsigned number of seconds since midnight, January 1, 1904; you can use a utility routine to convert this to a date/time record. Date/time records are defined as follows: TYPE DateTimeRec = RECORD year: INTEGER; {1904 to 2040} month: INTEGER; {1 to 12 for January to December} day: INTEGER; {1 to 31} hour: INTEGER; {0 to 23} minute: INTEGER; {0 to 59} second: INTEGER; {0 to 59} dayOfWeek: INTEGER {1 to 7 for Sunday to Saturday} END; æKY Delay æFp OSUtils.p æT PROCEDURE æTN $A03B æD PROCEDURE Delay(numTicks: LONGINT;VAR finalTicks: LONGINT); æDT Delay(numTicks,finalTicks); æRT 2 æRI Delay procedure II-384 æC Trap macro _Delay On entry A0: numTicks (long word) On exit D0: finalTicks (long word) Delay causes the system to wait for the number of ticks (sixtieths of a second) specified by numTicks, and returns in finalTicks the total number of ticks from system startup to the end of the delay. Warning: Don’t rely on the duration of the delay being exact; it will usually be accurate to within one tick, but may be off by more than that. The Delay procedure enables all interrupts and checks the tick count that’s incremented during the vertical retrace interrupt; however, it’s possible for this interrupt to be disabled by other interrupts, in which case the duration of the delay will not be exactly what you requested. Assembly-language note: On exit from this procedure, register D0 contains the value of the global variable Ticks as measured at the end of the delay. æKY Dequeue æFp OSUtils.p æT FUNCTION æTN $A96E æD FUNCTION Dequeue(qElement: QElemPtr;qHeader: QHdrPtr): OSErr; æDT myVariable := Dequeue(qElement,qHeader); æRI Dequeue function II-383 æC Trap macro _Dequeue On entry A0: qEntry (pointer) A1: theQueue (pointer) On exit A1: theQueue (pointer) D0: result code (word) Dequeue removes the queue entry pointed to by qEntry from the queue specified by theQueue (without deallocating the entry) and adjusts other entries in the queue accordingly. Note: The note under Enqueue above also applies here. In this case, the amount of time interrupts are disabled depends on the length of the queue and the position of the entry in the queue. Note: To remove all entries from a queue, you can just clear all the fields of the queue’s header. Result codes noErr No error qErr Entry not in specified queue æKY DTInstall æFp OSUtils.p æT FUNCTION æTN $A075 æD FUNCTION DTInstall(dtTaskPtr: QElemPtr): OSErr; æDT myVariable := DTInstall(dtTaskPtr); æRI DTInstall function V-467 æC _____________________________________________________________________________________ Trap macro _DTInstall On entry A0: dtTaskPtr (pointer) On exit D0: result code (word) Note: To reduce overhead at interrupt time, instead of executing the _DTInstall trap you can load the jump vector jDTInstall into an address register other than A0 and execute a JSR instruction using that register. _____________________________________________________________________________________ DTInstall adds the specified task to the deferred task queue. Your application must fill in all fields of the task except qLink. DTInstall returns one of the result codes listed below. Result codes noErr No error vTypErr Invalid queue element æKY Enqueue æFp OSUtils.p æT PROCEDURE æTN $A96F æD PROCEDURE Enqueue(qElement: QElemPtr;qHeader: QHdrPtr); æDT Enqueue(qElement,qHeader); æRI Enqueue procedure II-382 æC Trap macro _Enqueue On entry A0: qEntry (pointer) A1: theQueue (pointer) On exit A1: theQueue (pointer) Enqueue adds the queue entry pointed to by qEntry to the end of the queue specified by theQueue. Note: Interrupts are disabled for a short time while the queue is updated. æKY env512KE æFp OSUtils.p æC env512KE = 1; æKY env68000 æFp OSUtils.p æC env68000 = 1; æKY env68010 æFp OSUtils.p æC env68010 = 2; æKY env68020 æFp OSUtils.p æC env68020 = 3; æKY env68030 æFp OSUtils.p æC env68030 = 4; æKY envAExtendKbd æFp OSUtils.p æC envAExtendKbd = 4; æKY envCPUUnknown æFp OSUtils.p æC envCPUUnknown = 0; {CPU types} æKY Environs æFp OSUtils.p æT PROCEDURE æD PROCEDURE Environs(VAR rom: INTEGER;VAR machine: INTEGER); æDT Environs(rom,machine); æRI Environs procedure II-385, IV-236 æC [Not in ROM] In the rom parameter, Environs returns the current ROM version number (for a Macintosh XL, the version number of the ROM image installed by MacWorks). To use the 128K ROM information described in this volume, the version number should be greater than or equal to 117 ($75). In the machine parameter, Environs returns an indication of which machine is in use, as follows: CONST macXLMachine = 0; {Macintosh XL} macMachine = 1; {Macintosh 128K, 512K, 512K upgraded, } { 512K enhanced, or Macintosh Plus} Note: The machine parameter does not distinguish between the Macintosh 128K, 512K, 512K upgraded, 512K enhanced, and Macintosh Plus. Assembly-language note: From assembly language, you can get this information from the word that’s at an offset of 8 from the beginning of ROM (which is stored in the global variable ROMBase). The format of this word is $00xx for the Macintosh 128K, 512K, 512K enhanced, or Macintosh Plus, and $xxFF for the Macintosh XL, where xx is the ROM version number. (The ROM version number will always be between $01 and $FE.) æKY envMac æFp OSUtils.p æC envMac = -1; {Environs Equates} æKY envMacAndPad æFp OSUtils.p æC envMacAndPad = 2; æKY envMachUnknown æFp OSUtils.p æC envMachUnknown = 0; æKY envMacKbd æFp OSUtils.p æC envMacKbd = 1; æKY envMacPlus æFp OSUtils.p æC envMacPlus = 2; æKY envMacPlusKbd æFp OSUtils.p æC envMacPlusKbd = 3; æKY envSE æFp OSUtils.p æC envSE = 3; æKY envSE30 æFp OSUtils.p æC envSE30 = 7; æKY envStandADBKbd æFp OSUtils.p æC envStandADBKbd = 5; æKY envUnknownKbd æFp OSUtils.p æC envUnknownKbd = 0; {Keyboard types} æKY envXL æFp OSUtils.p æC envXL = -2; æKY EqualString æFp OSUtils.p æT FUNCTION æTN $A03C æD FUNCTION EqualString(str1: Str255;str2: Str255;caseSens: BOOLEAN;diacSens: BOOLEAN): BOOLEAN; æDT myVariable := EqualString(str1,str2,caseSens,diacSens); æRI EqualString function II-377 æC Assembly-language note: The trap macros for these utility routines have optional arguments corresponding to the Pascal flags passed to the routines. When present, such an argument sets a certain bit of the routine trap word; this is equivalent to setting the corresponding Pascal flag to either TRUE or FALSE, depending on the flag. The trap macros for these routines are listed with all the possible permutations of arguments. Whichever permutation you use, you must type it exactly as shown. (The syntax shown applies to the Lisa Workshop Assembler; programmers using another development system should consult its documentation for the proper syntax.) Trap macro _CmpString _CmpString ,MARKS (sets bit 9, for diacSens=FALSE) _CmpString ,CASE (sets bit 10, for caseSens=TRUE) _CmpString ,MARKS,CASE (sets bits 9 and 10) On entry A0: pointer to first character of first string A1: pointer to first character of second string D0: high-order word: length of first string low-order word: length of second string On exit D0: 0 if strings equal, 1 if strings not equal (long word) EqualString compares the two given strings for equality on the basis of their ASCII values. If caseSens is TRUE, uppercase characters are distinguished from the corresponding lowercase characters. If diacSens is FALSE, diacritical marks are ignored during the comparison. The function returns TRUE if the strings are equal. Note: See also the International Utilities Package function IUEqualString. æKY false32b,true32b æFp OSUtils.p æC { Addressing modes } false32b = 0; {24-bit addressing mode} true32b = 1; {32-bit addressing mode} æKY FlushDataCache æFp OSUtils.p æT PROCEDURE æD PROCEDURE FlushDataCache; æDT FlushDataCache; æKY FlushInstructionCache æFp OSUtils.p æT PROCEDURE æD PROCEDURE FlushInstructionCache; æDT FlushInstructionCache; æKY GetDateTime æFp OSUtils.p æT PROCEDURE æD PROCEDURE GetDateTime(VAR secs: LONGINT); æDT GetDateTime(secs); æRI GetDateTime procedure II-378 æC GetDateTime returns in the secs parameter the contents of the low-memory location in which the date and time setting is stored; if this setting reflects the actual current date and time, secs will contain the number of seconds between midnight, January 1, 1904 and the time that the function was called. Note: If your application disables interrupts for longer than a second, the number of seconds returned will not be exact. Assembly-language note: Assembly-language programmers can just access the global variable Time. If you wish, you can convert the value returned by GetDateTime to a date/time record by calling the Secs2Date procedure. Note: Passing the value returned by GetDateTime to the International Utilities Package procedure IUDateString or IUTimeString will yield a string representing the corresponding date or time of day, respectively. æKY GetMMUMode æFp OSUtils.p æT FUNCTION æD FUNCTION GetMMUMode: SignedByte; æDT myVariable := GetMMUMode; æRT 228 æRI GetMMUMode function V-592 æC [Not in ROM] GetMMUMode returns the address translation mode currently in use. Assembly-language note: Assembly-language programmers can determine the current address mode by testing the contents of the global variable MMU32Bit; it’s TRUE if 32-bit mode is in effect. •••Refer to Technical Note #228:••• æKY GetSysPPtr æFp OSUtils.p æT FUNCTION æD FUNCTION GetSysPPtr: SysPPtr; æDT myVariable := GetSysPPtr; æRI GetSysPPtr function II-381 æC [Not in ROM] GetSysPPtr returns a pointer to the low-memory copy of parameter RAM. You can examine the values stored in its various fields, or change them before calling WriteParam (below). Assembly-language note: Assembly-language programmers can simply access the global variables corresponding to the low-memory copy of parameter RAM. These variables, which begin at the address SysParam, are listed in the summary. æKY GetTime æFp OSUtils.p æT PROCEDURE æD PROCEDURE GetTime(VAR d: DateTimeRec); æDT GetTime(d); æRI GetTime procedure II-380 æC GetTime takes the number of seconds elapsed since midnight, January 1, 1904 (obtained by calling GetDateTime), converts that value into a date and time (by calling Secs2Date), and returns the result in the date parameter. Assembly-language note: From assembly language, you can pass the value of the global variable Time to Secs2Date. æKY GetTrapAddress æFp OSUtils.p æT FUNCTION æTN $A146 æD FUNCTION GetTrapAddress(trapNum: INTEGER): LONGINT; æDT myVariable := GetTrapAddress(trapNum); æRT 2 æRI GetTrapAddress function II-384, IV-234, N2-4 æC Trap macro _GetTrapAddress On entry D0: trapNum (word) On exit A0: address of routine GetTrapAddress returns the address of a routine currently installed in the trap dispatch table under the trap number designated by trapNum. To find out the trap number for a particular routine, see Appendix C. Assembly-language note: When you use this technique to bypass the trap dispatcher, you don’t get the extra level of register saving. The routine itself will preserve A2-A6 and D3-D7, but if you want any other registers preserved across the call you have to save and restore them yourself. æKY HandAndHand æFp OSUtils.p æT FUNCTION æTN $A9E4 æD FUNCTION HandAndHand(aHndl: Handle;bHndl: Handle): OSErr; æDT myVariable := HandAndHand(aHndl,bHndl); æMM æRI HandAndHand function II-375 æC Trap macro _HandAndHand On entry A0: aHndl (handle) A1: bHndl (handle) On exit A0: bHndl (handle) D0: result code (word) HandAndHand concatenates the information to which aHndl is a handle onto the end of the information to which bHndl is a handle. Warning: HandAndHand dereferences aHndl, so be sure to call the Memory Manager procedure HLock to lock the block before calling HandAndHand. Result codes noErr No error memFullErr Not enough room in heap zone nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY HandToHand æFp OSUtils.p æT FUNCTION æTN $A9E1 æD FUNCTION HandToHand(VAR theHndl: Handle): OSErr; æDT myVariable := HandToHand(theHndl); æMM æRI HandToHand function II-374 æC Trap macro _HandToHand On entry A0: theHndl (handle) On exit A0: theHndl (handle) D0: result code (word) HandToHand copies the information to which theHndl is a handle and returns a new handle to the copy in theHndl. Since HandToHand replaces the input parameter with a new handle, you should retain the original value of the input parameter somewhere else, or you won’t be able to access it. For example: VAR x,y: Handle; err: OSErr; y := x; err := HandToHand(y) The original handle remains in x while y becomes a different handle to an identical copy of the data. Result codes noErr No error memFullErr Not enough room in heap zone nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY InitUtil æFp OSUtils.p æT FUNCTION æTN $A03F æD FUNCTION InitUtil: OSErr; æDT myVariable := InitUtil; æRI InitUtil function II-380 æC Trap macro _InitUtil On exit D0: result code (word) •••Refer to Figure 4.••• Figure 4–Parameter RAM Routines InitUtil copies the contents of parameter RAM into 20 bytes of low memory and copies the date and time from the clock chip into its own low-memory location. This routine is called at system startup; you’ll probably never need to call it yourself. Assembly-language note: InitUtil copies parameter RAM into 20 bytes starting at the address SysParam and copies the date and time into the global variable Time. If the validity status in parameter RAM is not $A8 when InitUtil is called, an error is returned as the result code, and the default values (given in the “Parameter RAM” section) are read into the low-memory copy of parameter RAM; these values are then written to the clock chip itself. Result codes noErr No error prInitErr Validity status not $A8 æKY KeyTrans æFp OSUtils.p æT FUNCTION æTN $A9C3 æD FUNCTION KeyTrans(transData: Ptr;keycode: INTEGER;VAR state: LONGINT): LONGINT; æDT myVariable := KeyTrans(transData,keycode,state); æRT 160 æRI KeyTrans function V-195, N160 æC [256K ROM] KeyTrans lets your application convert key codes to ASCII values as determined by a 'KCHR' resource. The 'KCHR' resource type is discussed in the Resource Manager chapter. TransData points to a 'KCHR' resource, which maps virtual key codes to ASCII values. The keycode parameter is a 16-bit value with the structure shown in Figure 9. •••Refer to Figure 9.••• Figure 9–Keycode Parameter Structure The state parameter is a value maintained by the Toolbox. Your application should save it between calls to KeyTrans. If your application changes transData to point to a different 'KCHR' resource, it should reset the state value to 0. KeyTrans returns a 32-bit value with the structure shown in Figure 10. In this structure, ASCII 1 is the ASCII value of the first character generated by the key code parameter; reserved1 is an extension for future “16-bit ASCII” coding. ASCII 2 and reserved2 have the same meanings for a possible second character generated by key code—for example, if key code designates an alphabetic character with a separate accent character. •••Refer to Figure 10.••• Figure 10–KeyTrans Return Structure Assembly-language note: The macro you invoke to call KeyTrans from assembly language is named _KeyTrans. Its parameters are passed on the stack. æKY macXLMachine,macMachine æFp OSUtils.p æC { Values returned by Environs procedure } macXLMachine = 0; {Macintosh XL} macMachine = 1; {Macintosh 128K, 512K, 512K upgraded, } { 512K enhanced, or Macintosh Plus} æKY NGetTrapAddress æFp OSUtils.p æT FUNCTION æD FUNCTION NGetTrapAddress(trapNum: INTEGER;tTyp: TrapType): LONGINT; æDT myVariable := NGetTrapAddress(trapNum,tTyp); æRT 156, 212 æRI NGetTrapAddress function IV-234, N156-3 æC [Not in ROM] NGetTrapAddress is identical to GetTrapAddress except that it requires you to specify in tType whether the given routine is an Operating System or a Toolbox trap. Trap macro _GetTrapAddress ,NEWOS (bit 9 set, bit 10 clear) _GetTrapAddress ,NEWTOOL (bit 9 set, bit 10 set) On entry D0: trapNum (word) On exit A0: address of routine æKY NSetTrapAddress æFp OSUtils.p æT PROCEDURE æD PROCEDURE NSetTrapAddress(trapAddr: LONGINT;trapNum: INTEGER;tTyp: TrapType); æDT NSetTrapAddress(trapAddr,trapNum,tTyp); æRI NSetTrapAddress procedure IV-234 æC [Not in ROM] NSetTrapAddress is identical to SetTrapAddress except that it requires you to specify in tType whether the given routine is an Operating System or a Toolbox trap. Trap macro _SetTrapAddress ,NEWOS (bit 9 set, bit 10 clear) _SetTrapAddress ,NEWTOOL (bit 9 set, bit 10 set) On entry A0: trapAddr (address) D0: trapNum (word) æKY PtrAndHand æFp OSUtils.p æT FUNCTION æTN $A9EF æD FUNCTION PtrAndHand(ptr1: Ptr;hndl: Handle;size: LONGINT): OSErr; æDT myVariable := PtrAndHand(ptr1,hndl,size); æMM æRI PtrAndHand function II-376 æC Trap macro _PtrAndHand On entry A0: pntr (pointer) A1: hndl (handle) D0: size (long word) On exit A0: hndl (handle) D0: result code (word) PtrAndHand takes the number of bytes specified by the size parameter, beginning at the location specified by pntr, and concatenates them onto the end of the information to which hndl is a handle. Result codes noErr No error memFullErr Not enough room in heap zone nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY PtrToHand æFp OSUtils.p æT FUNCTION æTN $A9E3 æD FUNCTION PtrToHand(srcPtr: Ptr;VAR dstHndl: Handle;size: LONGINT): OSErr; æDT myVariable := PtrToHand(srcPtr,dstHndl,size); æMM æRI PtrToHand function II-375 æC Trap macro _PtrToHand On entry A0: srcPtr (pointer) D0: size (long word) On exit A0: dstHndl (handle) D0: result code (word) PtrToHand returns in dstHndl a newly created handle to a copy of the number of bytes specified by the size parameter, beginning at the location specified by srcPtr. Result codes noErr No error memFullErr Not enough room in heap zone æKY PtrToXHand æFp OSUtils.p æT FUNCTION æTN $A9E2 æD FUNCTION PtrToXHand(srcPtr: Ptr;dstHndl: Handle;size: LONGINT): OSErr; æDT myVariable := PtrToXHand(srcPtr,dstHndl,size); æMM æRI PtrToXHand function II-375 æC Trap macro _PtrToXHand On entry A0: srcPtr (pointer) A1: dstHndl (handle) D0: size (long word) On exit A0: dstHndl (handle) D0: result code (word) PtrToXHand takes the existing handle specified by dstHndl and makes it a handle to a copy of the number of bytes specified by the size parameter, beginning at the location specified by srcPtr. Result codes noErr No error memFullErr Not enough room in heap zone nilHandleErr NIL master pointer memWZErr Attempt to operate on a free block æKY QTypes,dummyType,vType,ioQType,drvQType,evType,fsQType æFp OSUtils.p æC QTypes = (dummyType,vType,ioQType,drvQType,evType,fsQType ); æKY ReadDateTime æFp OSUtils.p æT FUNCTION æTN $A039 æD FUNCTION ReadDateTime(VAR time: LONGINT): OSErr; æDT myVariable := ReadDateTime(time); æRI ReadDateTime function II-378 æC Trap macro _ReadDateTime On entry A0: pointer to long word secs On exit A0: pointer to long word secs D0: result code (word) ReadDateTime copies the date and time stored in the clock chip to a low-memory location and returns it in the secs parameter. This routine is called at system startup; you’ll probably never need to call it yourself. Instead you’ll call GetDateTime (see below). Assembly-language note: The low-memory location to which ReadDateTime copies the date and time is the global variable Time. Result codes noErr No error clkRdErr Unable to read clock æKY RelString æFp OSUtils.p æT FUNCTION æTN $A050 æD FUNCTION RelString(str1: Str255;str2: Str255;caseSens: BOOLEAN;diacSens: BOOLEAN): INTEGER; æDT myVariable := RelString(str1,str2,caseSens,diacSens); æRI RelString function IV-234 æC Assembly-language note: The trap macros for these utility routines have optional arguments corresponding to the Pascal flags passed to the routines. When present, such an argument sets a certain bit of the routine trap word; this is equivalent to setting the corresponding Pascal flag to either TRUE or FALSE, depending on the flag. The trap macros for these routines are listed with all the possible permutations of arguments. Whichever permutation you use, you must type it exactly as shown. (The syntax shown applies to the Lisa Workshop Assembler; programmers using another development system should consult its documentation for the proper syntax.) RelString is similar to EqualString except that it indicates whether the first string is less than, equal to, or greater than the second string by returning either –1, 0, or 1 respectively. Trap macro _RelString _RelString ,MARKS (sets bit 9, for diacSens=FALSE) _RelString ,CASE (sets bit 10, for caseSens=TRUE) _RelString ,MARKS,CASE (sets bits 9 and 10) On entry A0: pointer to first character of first string A1: pointer to first character of second string D0: high-order word: length of first string low-order word: length of second string On exit D0: –1 if first string less than second, 0 if equal, 1 if first string greater than second (long word) RelString follows the sort order described in the International Utilities Package chapter except for the reordering of the following ligatures: Æ falls between Å and a æ falls between å and B Œ falls between Ø and o œ falls between ø and P ß falls between s and T If diacSens is FALSE, diacritical marks are ignored; RelString strips diacriticals according to the following table: A <-- Ä, Å, À, Ã C <-- Ç E <-- É N <-- Ñ O <-- Ö, Õ, Ø U <-- Ü a <-- á, à, â, ä, ã, å, ª c <-- ç e <-- é, è, ê, ë i <-- í, ì, î, ï n <-- ñ o <-- ó, ò, ô, ö, õ, ø, º u <-- ú, ù, û, ü y <-- ÿ Note: This stripping is identical to that performed by the UprString procedure when the diacSens parameter is FALSE. If caseSens is FALSE, the comparison is not case-sensitive; RelString performs a conversion from lower-case to upper-case characters according to the following table: A <-- a ... <-- ... Z <-- z À <-- à Ã <-- ã Ä <-- ä Å <-- å Æ <-- æ Ç <-- ç É <-- é Ñ <-- ñ Ö <-- ö Õ <-- õ Ø <-- ø Œ <-- œ Ü <-- ü Note: This conversion is identical to that performed by the UprString procedure. æKY Restart æFp OSUtils.p æT PROCEDURE æD PROCEDURE Restart; æDT Restart; æMM æRT 208 æRI Restart procedure II-385 æC [Not in ROM] This procedure restarts the system. Assembly-language note: From assembly language, you can give the following instructions to restart the system: MOVE.L ROMBase,A0 JMP $0A(A0) Note: The procedures SetUpA5 and RestoreA5 were formerly documented in this chapter; however, two routines with more functionality are now available with the MPW 3.0 and later libraries. The routines SetCurrentA5 and SetA5 are documented in Macintosh Technical Note #208. •••Refer to Technical Note #208:••• æKY Secs2Date æFp OSUtils.p æT PROCEDURE æTN $A9C6 æD PROCEDURE Secs2Date(s: LONGINT;VAR d: DateTimeRec); æDT Secs2Date(s,d); æRI Secs2Date procedure II-380 æC Trap macro _Secs2Date On entry D0: secs (long word) On exit A0: pointer to date/time record Secs2Date takes a number of seconds elapsed since midnight, January 1, 1904 as specified by the secs parameter, converts it to the corresponding date and time, and returns the corresponding date/time record in the date parameter. æKY SetCurrentA5 æFp OSUtils.p æT FUNCTION æD FUNCTION SetCurrentA5: LONGINT; æDT myVariable := SetCurrentA5; æRT 208 æKY SetDateTime æFp OSUtils.p æT FUNCTION æTN $A03A æD FUNCTION SetDateTime(time: LONGINT): OSErr; æDT myVariable := SetDateTime(time); æRI SetDateTime function II-379 æC Trap macro _SetDateTime On entry D0: secs (long word) On exit D0: result code (word) SetDateTime takes a number of seconds since midnight, January 1, 1904, as specified by the secs parameter, and writes it to the clock chip as the current date and time. It then attempts to read the value just written and verify it by comparing it to the secs parameter. Assembly-language note: SetDateTime updates the global variable Time to the value of the secs parameter. Result codes noErr No error clkWrErr Time written did not verify clkRdErr Unable to read clock æKY SetTime æFp OSUtils.p æT PROCEDURE æD PROCEDURE SetTime(d: DateTimeRec); æDT SetTime(d); æRI SetTime procedure II-380 æC SetTime takes the date and time specified by the date parameter, converts it into the corresponding number of seconds elapsed since midnight, January 1, 1904 (by calling Date2Secs), and then writes that value to the clock chip as the current date and time (by calling SetDateTime). Assembly-language note: From assembly language, you can just call Date2Secs and SetDateTime directly. æKY SetTrapAddress æFp OSUtils.p æT PROCEDURE æTN $A047 æD PROCEDURE SetTrapAddress(trapAddr: LONGINT;trapNum: INTEGER); æDT SetTrapAddress(trapAddr,trapNum); æRT 2 æRI SetTrapAddress procedure II-384, IV-234, N2-4 æC Trap macro _SetTrapAddress On entry A0: trapAddr (address) D0: trapNum (word) SetTrapAddress installs in the trap dispatch table a routine whose address is trapAddr; this routine is installed under the trap number designated by trapNum. Warning: Since the trap dispatch table can address locations within a range of only 64K bytes from the beginning of the system heap, the routine you install should be in the system heap. Assembly-language note: To use GetTrapAddress and SetTrapAddress with 128K ROM routines, set bit 9 of the trap word to indicate the new trap numbering. The state of bit 10 then determines whether the intended trap is a Toolbox or Operating System trap. You can set these two bits with the arguments NEWOS and NEWTOOL. Of course, the 64K ROM versions of GetTrapAddress and SetTrapAddress will fail if applied to traps that exist only in the 128K ROM. The NGetTrapAddress and NSetTrapAddress routines list the possible permutations of arguments. (The syntax shown applies to the Lisa Workshop Assembler; programmers using another development system should consult its documentation for the proper syntax.) æKY sortsAfter æFp OSUtils.p æC sortsAfter = 1; {first string > second string} æKY sortsBefore æFp OSUtils.p æC sortsBefore = -1; {first string < second string} æKY sortsEqual æFp OSUtils.p æC sortsEqual = 0; {first string = second string} æKY SwapDataCache æFp OSUtils.p æT FUNCTION æD FUNCTION SwapDataCache(cacheEnable: BOOLEAN): BOOLEAN; æDT myVariable := SwapDataCache(cacheEnable); æKY SwapInstructionCache æFp OSUtils.p æT FUNCTION æD FUNCTION SwapInstructionCache(cacheEnable: BOOLEAN): BOOLEAN; æDT myVariable := SwapInstructionCache(cacheEnable); æKY SwapMMUMode æFp OSUtils.p æT PROCEDURE æTN $A05D æD PROCEDURE SwapMMUMode(VAR mode: SignedByte); æDT SwapMMUMode(mode); æRI SwapMMUMode procedure V-593, C1-6 æC Trap macro _SwapMMUMode On entry D0: mode (byte) On exit D0: mode (byte) SwapMMUMode sets the address translation mode to that specified by the mode parameter. The mode in use prior to the call is returned in mode, and can be restored with another call to SwapMMUMode. æKY SysBeep æFp OSUtils.p æT PROCEDURE æTN $A9C8 æD PROCEDURE SysBeep(duration: INTEGER); æDT SysBeep(duration); æMM æRI SysBeep procedure II-385, V-592 æC SysBeep causes the system to beep for approximately the number of ticks specified by the duration parameter. The sound decays from loud to soft; after about five seconds it’s inaudible. The initial volume of the beep depends on the current speaker volume setting, which the user can adjust with the Control Panel desk accessory. If the speaker volume has been set to 0 (silent), SysBeep instead causes the menu bar to blink once. Assembly-language note: Unlike all other Operating System Utilities, this procedure is stack-based. æKY SysEnvirons æFp OSUtils.p æT FUNCTION æTN $A090 æD FUNCTION SysEnvirons(versionRequested: INTEGER;VAR theWorld: SysEnvRec): OSErr; æDT myVariable := SysEnvirons(versionRequested,theWorld); æRT 67, 103, 156, 184, 190, 207,212 æRI SysEnvirons function V-5, N129, N156 æC ——————————————————————————————————————————————————————————————————————————————— »DETERMINING THE FEATURES OF A MACHINE CompatibilityGuide _______________________________________________________________________________ As the Macintosh family grows, applications need a reliable and comprehensive way of determining what software and hardware features are available on a given machine. Although the Operating System Utilities routine Environs indicates the type of machine and ROM version running, it provides no help in distinguishing between the plethora of different software feature sets and hardware configurations that an application may encounter. A new function, SysEnvirons, provides detailed information about what software functionality (Color QuickDraw, as an example) is available, as well as what hardware devices (processors, peripherals, and so on) are installed or connected. All of the Toolbox Managers must be initialized before calling SysEnvirons. In addition, the AppleTalk Manager routine MPPOpen must be called if the driver version information in atDrvrVersNum is desired. SysEnvirons is not intended for use by device drivers, but can be called from desk accessories. (It does not assume that register A5 has been properly set up.) FUNCTION SysEnvirons (versionReqested: INTEGER; VAR theWorld: SysEnvRec) : OSErr; [Not in ROM] •••Refer to Technical Note #129:••• Trap macro _SysEnvirons On entry A0: sysEnvRec (pointer) D0: versReqested (word) On exit A0: sysEnvRec (pointer) D0: result code (word) Result codes noErr No error envNotPresent SysEnvirons trap not present envBadVers Nonpositive version number passed envVersTooBig Requested version of SysEnvirons call not available In theWorld, SysEnvirons returns a system environment record describing the features of the machine. Designed to be extendible, SysEnvirons will be updated as new features are added, and the system environment record that’s returned will be expanded. System File 4.1 contains version 1 of SysEnvirons; subsequent versions will be incremented by 1. The system environment record for version 1 of SysEnvirons contains the following fields: TYPE SysEnvRec = RECORD environsVersion: INTEGER; machineType: INTEGER; systemVersion: INTEGER; processor: INTEGER; hasFPU: BOOLEAN; hasColorQD: BOOLEAN; keyBoardType: INTEGER; atDrvrVersNum: INTEGER; sysVRefNum: INTEGER END; New versions of the call will add fields to this record. To distinguish between different versions of the call, and thereby between the different sizes of records they return, SysEnvirons returns its version number in the environsVersion field. If you request version 2, for instance, but only version 1 is available, the environsVersion field will contain the value 1, and the result code envVersTooBig will be returned. This tells you that only the information for version 1 has been returned in SysEnvRec. The MPW 2.0 interface files contain code, or “glue”, for System file versions earlier than 4.1, as well as for the 64K and the Macintosh XL ROMs. The glue checks for the existence of the trap at runtime; if the call does not exist, the glue fills in all fields of the record except systemVersion and returns the result code envNotPresent. Assembly-language note: As with the MoveHHi procedure, assembly-language programmers using MPW should link with the glue and execute JSR SysEnvirons If you’re using another development system, refer to its documentation for details. The machineType field returns one of the following constants: CONST envMachUnknown = 0; {new version of Macintosh--not covered } { by this version of SysEnvirons} env512KE = 1; {Macintosh 512K enhanced} envMacPlus = 2; {Macintosh Plus} envSE = 3; {Macintosh SE} envMacII = 4; {Macintosh II} envMacIIx = 5; {Macintosh IIx} envMacIIcx = 6; {Macintosh IIcx} envSE30 = 7; {Macintosh SE/30} envPortable = 8; {Macintosh Portable} envMacIIci = 9; {Macintosh IIci} In addition to these, the glue for SysEnvirons may return one of the following: CONST envMac = –1; {Macintosh with 64K ROM} envXL = –2; {Macintosh XL} The systemVersion field returns the version number of the System file represented as two byte-long numbers, separated by a period. (It is not a fixed point number.) For instance, System 4.1 returns $0410 or 04.10 in this field. (Applications can use this for compare operations.) If SysEnvirons is called while a system earlier than System 4.1 is running, the glue will return a $0 in this field, and the result code envNotPresent will be returned. The processor field returns one of the following constants: CONST envCPUUnknown = 0; {new processor--not yet covered by this } { version of SysEnvirons} env68000 = 1; {MC68000 processor} env68010 = 2; {MC68010 processor} env68020 = 3; {MC68020 processor} env68030 = 4; {MC68030 processor} The hasFPU field tells whether or not a Motorola MC68881 floating-point coprocessor unit is present. (This field does not apply to third-party memory-mapped coprocessor add-ons.) The hasColorQD field tells whether or not Color QuickDraw is present. It does not indicate whether or not a color screen is present (high-level QuickDraw calls provide this information). The keyboardType field returns one of the following constants: CONST envUnknownKbd = 0; {Macintosh Plus keyboard with keypad} envMacKbd = 1; {Macintosh keyboard} envMacAndPad = 2; {Macintosh keyboard and keypad} envMacPlusKbd = 3; {Macintosh Plus keyboard} envAExtendKbd = 4; {Apple Extended keyboard} envStandADBKbd = 5; {Apple Standard keyboard} envPortADBKbd = 6; {Macintosh Portable keyboard} envPortISOADBKbd = 7; {Macintosh Portable keyboard (ISO)} envStdISOADBKbd = 8; {Apple Standard keyboard (ISO)} envExtISOADBKbd = 9; {Apple Extended keyboard (ISO)} If the Apple Desktop Bus™ is in use, this field returns the keyboard type of the keyboard on which a keystroke was last made. ATDrvrVersNum returns the version number of AppleTalk, if it’s been loaded (that is, if MPPOpen has been called); otherwise, 0 is returned in this field. SysVRefNum returns the working directory reference number (or volume reference number) of the directory that contains the currently open System file. _______________________________________________________________________________ æKY SysEnvRec æFp OSUtils.p æT RECORD æC SysEnvRec = RECORD environsVersion: INTEGER; machineType: INTEGER; systemVersion: INTEGER; processor: INTEGER; hasFPU: BOOLEAN; hasColorQD: BOOLEAN; keyBoardType: INTEGER; atDrvrVersNum: INTEGER; sysVRefNum: INTEGER; END; The system environment record for version 1 of SysEnvirons contains the following fields: TYPE SysEnvRec = RECORD environsVersion: INTEGER; machineType: INTEGER; systemVersion: INTEGER; processor: INTEGER; hasFPU: BOOLEAN; hasColorQD: BOOLEAN; keyBoardType: INTEGER; atDrvrVersNum: INTEGER; sysVRefNum: INTEGER END; New versions of the call will add fields to this record. To distinguish between different versions of the call, and thereby between the different sizes of records they return, SysEnvirons returns its version number in the environsVersion field. If you request version 2, for instance, but only version 1 is available, the environsVersion field will contain the value 1, and the result code envVersTooBig will be returned. This tells you that only the information for version 1 has been returned in SysEnvRec. The MPW 2.0 interface files contain code, or “glue”, for System file versions earlier than 4.1, as well as for the 64K and the Macintosh XL ROMs. The glue checks for the existence of the trap at runtime; if the call does not exist, the glue fills in all fields of the record except systemVersion and returns the result code envNotPresent. Assembly-language note: As with the MoveHHi procedure, assembly-language programmers using MPW should link with the glue and execute JSR SysEnvirons If you’re using another development system, refer to its documentation for details. The machineType field returns one of the following constants: CONST envMachUnknown = 0; {new version of Macintosh--not covered } { by this version of SysEnvirons} env512KE = 1; {Macintosh 512K enhanced} envMacPlus = 2; {Macintosh Plus} envSE = 3; {Macintosh SE} envMacII = 4; {Macintosh II} envMacIIx = 5; {Macintosh IIx} envMacIIcx = 6; {Macintosh IIcx} envSE30 = 7; {Macintosh SE/30} envPortable = 8; {Macintosh Portable} envMacIIci = 9; {Macintosh IIci} In addition to these, the glue for SysEnvirons may return one of the following: CONST envMac = –1; {Macintosh with 64K ROM} envXL = –2; {Macintosh XL} The systemVersion field returns the version number of the System file represented as two byte-long numbers, separated by a period. (It is not a fixed point number.) For instance, System 4.1 returns $0410 or 04.10 in this field. (Applications can use this for compare operations.) If SysEnvirons is called while a system earlier than System 4.1 is running, the glue will return a $0 in this field, and the result code envNotPresent will be returned. The processor field returns one of the following constants: CONST envCPUUnknown = 0; {new processor--not yet covered by this } { version of SysEnvirons} env68000 = 1; {MC68000 processor} env68010 = 2; {MC68010 processor} env68020 = 3; {MC68020 processor} env68030 = 4; {MC68030 processor} The hasFPU field tells whether or not a Motorola MC68881 floating-point coprocessor unit is present. (This field does not apply to third-party memory-mapped coprocessor add-ons.) The hasColorQD field tells whether or not Color QuickDraw is present. It does not indicate whether or not a color screen is present (high-level QuickDraw calls provide this information). The keyboardType field returns one of the following constants: CONST envUnknownKbd = 0; {Macintosh Plus keyboard with keypad} envMacKbd = 1; {Macintosh keyboard} envMacAndPad = 2; {Macintosh keyboard and keypad} envMacPlusKbd = 3; {Macintosh Plus keyboard} envAExtendKbd = 4; {Apple Extended keyboard} envStandADBKbd = 5; {Apple Standard keyboard} envPortADBKbd = 6; {Macintosh Portable keyboard} envPortISOADBKbd = 7; {Macintosh Portable keyboard (ISO)} envStdISOADBKbd = 8; {Apple Standard keyboard (ISO)} envExtISOADBKbd = 9; {Apple Extended keyboard (ISO)} If the Apple Desktop Bus™ is in use, this field returns the keyboard type of the keyboard on which a keystroke was last made. ATDrvrVersNum returns the version number of AppleTalk, if it’s been loaded (that is, if MPPOpen has been called); otherwise, 0 is returned in this field. SysVRefNum returns the working directory reference number (or volume reference number) of the directory that contains the currently open System file. æKY TrapType,OSTrap,ToolTrap æFp OSUtils.p æC TrapType = (OSTrap,ToolTrap); æKY UprString æFp OSUtils.p æT PROCEDURE æTN $A054 æD PROCEDURE UprString(VAR theString: Str255;diacSens: BOOLEAN); æDT UprString(theString,diacSens); æRI UprString procedure II-377 æC Assembly-language note: The trap macros for these utility routines have optional arguments corresponding to the Pascal flags passed to the routines. When present, such an argument sets a certain bit of the routine trap word; this is equivalent to setting the corresponding Pascal flag to either TRUE or FALSE, depending on the flag. The trap macros for these routines are listed with all the possible permutations of arguments. Whichever permutation you use, you must type it exactly as shown. (The syntax shown applies to the Lisa Workshop Assembler; programmers using another development system should consult its documentation for the proper syntax.) Trap macro _UprString _UprString ,MARKS (sets bit 9, for diacSens=FALSE) On entry A0: pointer to first character of string D0: length of string (word) On exit A0: pointer to first character of string UprString converts any lowercase letters in the given string to uppercase, returning the converted string in theString. In addition, diacritical marks are stripped from the string if diacSens is FALSE. æKY useAsync æFp OSUtils.p æC useAsync = 2; æKY useATalk æFp OSUtils.p æC useATalk = 1; æKY useExtClk æFp OSUtils.p æC useExtClk = 3; {Externally clocked} æKY useFree æFp OSUtils.p æC useFree = 0; æKY useMIDI æFp OSUtils.p æC useMIDI = 4; æKY WriteParam æFp OSUtils.p æT FUNCTION æTN $A038 æD FUNCTION WriteParam: OSErr; æDT myVariable := WriteParam; æRI WriteParam function II-382 æC Trap macro _WriteParam On entry A0: SysParam (pointer) D0: MinusOne (long word) (You have to pass the values of these global variables for historical reasons.) On exit D0: result code (word) WriteParam writes the low-memory copy of parameter RAM to the clock chip. You should previously have called GetSysPPtr and changed selected values as desired. WriteParam also attempts to verify the values written by reading them back in and comparing them to the values in the low-memory copy. Note: If you’ve accidentally written incorrect values into parameter RAM, the system may not be able to start up. If this happens, you can reset parameter RAM by removing the battery, letting the Macintosh sit turned off for about five minutes, and then putting the battery back in. Result codes noErr No error prWrErr Parameter RAM written did not verify æKY Packages.p æKL InitAllPacks InitPack IUCompString IUDatePString IUDateString IUEqualString IUGetIntl IUMagIDString IUMagString IUMetric IUSetIntl IUTimePString IUTimeString NumToString SFGetFile SFPGetFile SFPutFile StringToNum abbrevDate bdConv century currLeadingZ currNegSym currSymLead currTrailingZ DateForm dayLdingZ dmy dskInit dym flPoint getCancel getDlgID getDrive getEject getNmList getOpen getScroll hrLeadingZ Intl0Hndl Intl0Ptr Intl0Rec Intl1Hndl Intl1Ptr Intl1Rec intUtil listMgr longDate longDay longMonth longWeek longYear maxCountry mdy minCountry minLeadingZ mntLdingZ myd putCancel putDlgID putDrive putEject putName putSave secLeadingZ SFReply SFTypeList shortDate stdFile supDay supMonth supWeek supYear trFunc verArabia verAustralia verBelgiumLux verBritain verChina verCyprus verDenmark verFinland verFrance verFrCanada verFrSwiss verGermany verGreece verGrSwiss verIceland verIreland verIsrael verItaly verJapan verKorea verMalta verNetherlands verNorway verPortugal verSpain verSweden verTaiwan verThailand verTurkey verUS verYugoslavia ydm ymd zeroCycle æKY Intl0Hndl,Intl0Ptr,Intl0Rec æFp Packages.p æT TYPE æC Intl0Ptr = ^Intl0Rec; Intl0Hndl = ^Intl0Ptr; Intl0Rec = PACKED RECORD decimalPt: CHAR; {decimal point character} thousSep: CHAR; {thousands separator} listSep: CHAR; {list separator} currSym1: CHAR; {currency symbol} currSym2: CHAR; currSym3: CHAR; currFmt: Byte; {currency format} dateOrder: Byte; {order of short date elements} shrtDateFmt: Byte; {short date format} dateSep: CHAR; {date separator} timeCycle: Byte; {0 if 24-hour cycle, 255 if 12-hour} timeFmt: Byte; {time format} mornStr: PACKED ARRAY [1..4] OF CHAR; {trailing string for first 12-hour cycle} eveStr: PACKED ARRAY [1..4] OF CHAR; {trailing string for last 12-hour cycle} timeSep: CHAR; {time separator} time1Suff: CHAR; {trailing string for 24-hour cycle} time2Suff: CHAR; time3Suff: CHAR; time4Suff: CHAR; time5Suff: CHAR; time6Suff: CHAR; time7Suff: CHAR; time8Suff: CHAR; metricSys: Byte; {255 if metric, 0 if not} intl0Vers: INTEGER; {version information} END; æKY Intl1Hndl,Intl1Ptr,Intl1Rec æFp Packages.p æT TYPE æC Intl1Ptr = ^Intl1Rec; Intl1Hndl = ^Intl1Ptr; Intl1Rec = PACKED RECORD days: ARRAY [1..7] OF Str15; {day names} months: ARRAY [1..12] OF Str15; {month names} suppressDay: Byte; {0 for day name, 255 for none} lngDateFmt: Byte; {order of long date elements} dayLeading0: Byte; {255 for leading 0 in day number} abbrLen: Byte; {length for abbreviating names} st0: PACKED ARRAY [1..4] OF CHAR; {strings for long date format} st1: PACKED ARRAY [1..4] OF CHAR; st2: PACKED ARRAY [1..4] OF CHAR; st3: PACKED ARRAY [1..4] OF CHAR; st4: PACKED ARRAY [1..4] OF CHAR; intl1Vers: INTEGER; {version information} localRtn: ARRAY [0..0] OF INTEGER; {routine for localizing string comparison} END; æKY century æFp Packages.p æC century = 128; æKY currLeadingZ æFp Packages.p æC currLeadingZ = 128; æKY currNegSym æFp Packages.p æC currNegSym = 32; æKY currSymLead æFp Packages.p æC currSymLead = 16; æKY currTrailingZ æFp Packages.p æC currTrailingZ = 64; æKY DateForm,shortDate,longDate,abbrevDate æFp Packages.p æC DateForm = (shortDate,longDate,abbrevDate); æKY dayLdingZ æFp Packages.p æC dayLdingZ = 32; æKY dmy æFp Packages.p æC dmy = 1; æKY dym æFp Packages.p æC dym = 4; æKY getCancel æFp Packages.p æC getCancel = 3; æKY getDlgID æFp Packages.p æC getDlgID = -4000; æKY getDrive æFp Packages.p æC getDrive = 6; æKY getEject æFp Packages.p æC getEject = 5; æKY getNmList æFp Packages.p æC getNmList = 7; æKY getOpen æFp Packages.p æC getOpen = 1; æKY getScroll æFp Packages.p æC getScroll = 8; æKY hrLeadingZ æFp Packages.p æC hrLeadingZ = 128; æKY InitAllPacks æFp Packages.p æT PROCEDURE æTN $A9E6 æD PROCEDURE InitAllPacks; æDT InitAllPacks; æMM æRI InitAllPacks procedure I-484 æC InitAllPacks enables you to use all Macintosh packages (as though InitPack were called for each one). It will already have been called when your application starts up. æKY InitPack æFp Packages.p æT PROCEDURE æTN $A9E5 æD PROCEDURE InitPack(packID: INTEGER); æDT InitPack(packID); æMM æRI InitPack procedure I-484 æC InitPack enables you to use the package specified by packID, which is the package’s resource ID. (It gets a handle that will be used later to read the package into memory.) æKY IUCompString æFp Packages.p æT FUNCTION æD FUNCTION IUCompString(aStr: Str255;bStr: Str255): INTEGER; æDT myVariable := IUCompString(aStr,bStr); æMM æRI IUCompString function I-506, N58-1 æC IUCompString compares aStr and bStr as described above under "International String Comparison", taking both primary and secondary ordering into consideration. It returns one of the values listed below. Result Meaning Example aStr bStr -1 aStr is less than bStr 'Ab' 'ab' 0 aStr equals bStr 'Ab' 'Ab' 1 aStr is greater than bStr 'Ac' 'ab' æKY IUDatePString æFp Packages.p æT PROCEDURE æTN $A9ED æD PROCEDURE IUDatePString(dateTime: LONGINT;longFlag: DateForm;VAR result: Str255; intlParam: Handle); æDT IUDatePString(dateTime,longFlag,result,intlParam); æMM æRI IUDatePString procedure I-505 æC IUDatePString is the same as IUDateString except that it determines the exact format of the date from the resource whose handle is passed in intlParam, overriding the resource that would otherwise be used. æKY IUDateString æFp Packages.p æT PROCEDURE æTN $A9ED æD PROCEDURE IUDateString(dateTime: LONGINT;longFlag: DateForm;VAR result: Str255); æDT IUDateString(dateTime,longFlag,result); æMM æRI IUDateString procedure I-504 æC Given a date and time as returned by the Operating System Utility routine ReadDateTime, IUDateString returns in the result parameter a string that represents the corresponding date. The form parameter has the following data type: TYPE DateForm = (shortDate,longDate,abbrevDate); ShortDate requests the short date format, longDate the long date, and abbrevDate the abbreviated long date. IUDateString determines the exact format from international resource 0 for the short date or 1 for the long date. See Figure I-1 above for examples of the standard formats. Notice that the short date contains a space in place of a leading zero when the format specifies "no leading zero", so the length of the result is always the same for short dates. If the abbreviated long date is requested and the abbreviation length in international resource 1 is greater than the actual length of the name being abbreviated, IUDateString fills the abbreviation with NULL characters; the abbreviation length should not be greater than 15, the maximum name length. æFp PROCEDURE æD Given a date and time as returned by æMM æRI IUDateString procedure I-504 æKY IUEqualString æFp Packages.p æT FUNCTION æD FUNCTION IUEqualString(aStr: Str255;bStr: Str255): INTEGER; æDT myVariable := IUEqualString(aStr,bStr); æMM æRI IUEqualString function I-506, N58-1 æC IUEqualString compares aStr and bStr for equality without regard for secondary ordering, as described above under "international String Comparison". If the strings are equal, it returns 0; otherwise, it returns 1. For example, if the strings are 'Rose' and 'rose', IUEqualString considers them equal and returns 0. Note: See also EqualString in the Operating System Utilities manual. æMM æRI IUEqualString function I-506, N58-1 æKY IUGetIntl æFp Packages.p æT FUNCTION æD FUNCTION IUGetIntl(theID: INTEGER): Handle; æDT myVariable := IUGetIntl(theID); æMM æRT 153 æRI IUGetIntl function I-505 æC IUGetIntl returns a handle to the international resource numbered theID (0 or 1). It calls the Resource Manager function GetResource('INTL',theID). For example, if you want to access individual fields of international resource 0, you can do the following: VAR myHndl: Handle; int0: Intl0Hndl; ... myHndl := IUGetIntl(0); int0 := POINTER(ORD(myHndl)); æKY IUMagIDString æFp Packages.p æT FUNCTION æTN $A9ED æD FUNCTION IUMagIDString(aPtr: Ptr;bPtr: Ptr;aLen: INTEGER;bLen: INTEGER): INTEGER; æDT myVariable := IUMagIDString(aPtr,bPtr,aLen,bLen); æMM æRI IUMagIDString function I-507, N58-1 æC IUMagIDString is the same as IUEqualString (above) except that instead of comparing two Pascal strings, it compares the string defined by aPtr and aLen to the string defined by bPtr and bLen. The pointer points to the first character of the string (any byte in memory, not necessarily word-aligned), and the length specifies the number of characters in the string. æKY IUMagString æFp Packages.p æT FUNCTION æTN $A9ED æD FUNCTION IUMagString(aPtr: Ptr;bPtr: Ptr;aLen: INTEGER;bLen: INTEGER): INTEGER; æDT myVariable := IUMagString(aPtr,bPtr,aLen,bLen); æMM æRI IUMagString function I-506, N58-1 æC IUMagString is the same as IUCompString (above) except that instead of comparing two Pascal strings, it compares the string defined by aPtr and aLen to the string defined by bPtr and bLen. The pointer points to the first character of the string (any byte in memory, not necessarily word-aligned), and the length specifies the number of characters in the string. æKY IUMetric æFp Packages.p æT FUNCTION æTN $A9ED æD FUNCTION IUMetric: BOOLEAN; æDT myVariable := IUMetric; æMM æRI IUMetric function I-505 æC If international resource 0 specifies that the metric system is to be used, IUMetric returns TRUE; otherwise, it returns FALSE. æKY IUSetIntl æFp Packages.p æT PROCEDURE æTN $A9ED æD PROCEDURE IUSetIntl(refNum: INTEGER;theID: INTEGER;intlParam: Handle); æDT IUSetIntl(refNum,theID,intlParam); æMM æRI IUSetIntl procedure I-506 æC In the resource file having the reference number refNum, IUSetIntl sets the international resource numbered theID (0 or 1) to the data pointed to by intlParam. The data may be either an existing resource or data that hasn't yet been written to a resource file. IUSetIntl adds the resource to the specified file or replaces the resource if it's already there. æMM æRI IUTimePString procedure I-505 æKY IUTimePString æFp Packages.p æT PROCEDURE æTN $A9ED æD PROCEDURE IUTimePString(dateTime: LONGINT;wantSeconds: BOOLEAN;VAR result: Str255; intlParam: Handle); æDT IUTimePString(dateTime,wantSeconds,result,intlParam); æMM æRI IUTimePString procedure I-505 æC IUTimePString is the same as IUTimeString except that it determines the time format from the resource whose handle is passed in intlParam, overriding the resource that would otherwise be used. æMM æRI IUTimeString procedure I-505 æKY IUTimeString æFp Packages.p æT PROCEDURE æTN $A9ED æD PROCEDURE IUTimeString(dateTime: LONGINT;wantSeconds: BOOLEAN;VAR result: Str255); æDT IUTimeString(dateTime,wantSeconds,result); æMM æRI IUTimeString procedure I-505 æC Given a date and time as returned by the Operating System Utility routine ReadDateTime, IUTimeString returns in the result parameter a string that represents the corresponding time of day. If wantSeconds is TRUE, seconds are included in the time; otherwise, only the hour and minute are included. IUTimeSting determines the time format from international resource 0. See Figure I-1 above for examples of the standard formats. Notice that the time contains a space in place of a leading zero when the format specifies "no leading zero", so the length of the result is always the same. æKY listMgr,dskInit,stdFile,flPoint,trFunc,intUtil,bdConv æFp Packages.p æC { Resource IDs for packages } listMgr = 0; {List Manager} dskInit = 2; {Disk Initialization} stdFile = 3; {Standard File} flPoint = 4; {Floating-Point Arithmetic} trFunct = 5; {Transcendental Functions} intUtil = 6; {International Utilities} bdConv = 7; {Binary-Decimal Conversion} _______________________________________________________________________________ »ABOUT PACKAGES _______________________________________________________________________________ Packages are sets of data types and routines that are stored as resources and brought into memory only when needed. They serve as extensions to the Toolbox and Operating System, for the most part performing less common operations. The Macintosh packages, which are stored in the system resource file, include the following: • The Standard File Package, for presenting the standard user interface when a file is to be saved or opened. • The Disk Initialization Package, for initializing and naming new disks. This package is called by the Standard File Package; you’ll only need to call it in nonstandard situations. • The International Utilities Package, for accessing country-dependent information such as the formats for numbers, currency, dates, and times. • The Binary-Decimal Conversion Package, for converting integers to decimal strings and vice versa. • The Floating-Point Arithmetic Package, which supports extended-precision arithmetic according to IEEE Standard 754. • The Transcendental Functions Package, which contains trigonometric, logarithmic, exponential, and financial functions, as well as a random number generator. • The List Manager Package, for creating, displaying, and manipulating lists. The following Macintosh packages, previously stored only in the system resource file, are now also found in the 128K ROM: • The Binary-Decimal Conversion Package • The Floating-Point Arithmetic Package • The Transcendental Functions Package For compatibility with the 64K ROM, the above resources are still stored in the system resource file. The system resource file contains the following additional packages as well: • The List Manager Package, for creating, displaying, and manipulating lists. • The Standard File Package. • The Disk Initialization Package • The International Utilities Package Packages have the resource type 'PACK' and the following resource IDs: CONST listMgr = 0; {List Manager} dskInit = 2; {Disk Initialization} stdFile = 3; {Standard File} flPoint = 4; {Floating-Point Arithmetic} trFunc = 5; {Transcendental Functions} intUtil = 6; {International Utilities} bdConv = 7; {Binary-Decimal Conversion} The Package Manager has been extended to allow for eight additional packages. All packages are reserved for use by Apple. Assembly-language note: Just as for the routines in ROM, you can invoke a package routine with a macro that has the same name as the routine preceded by an underscore. These macros, however, aren’t trap macros themselves; instead, they expand to invoke the trap macro _PackN, where N is the resource ID of the package. The package determines which routine to execute from the routine selector, an integer that’s passed to it in a word on the stack. For example, the routine selector for the Standard File Package procedure SFPutFile is 1, so invoking the macro _SFPutFile pushes 1 onto the stack and invokes _Pack3. The routines in the Floating-Point Arithmetic and Transcendental Functions packages also invoke a trap macro of the form _PackN, but the mechanism through which they’re called is somewhat different, as explained in the chapter describing those packages. æKY longDay æFp Packages.p æC longDay = 0; {day of the month} æKY longMonth æFp Packages.p æC longMonth = 2; {month of the year} æKY longWeek æFp Packages.p æC longWeek = 1; {day of the week} æKY longYear æFp Packages.p æC longYear = 3; {year} æKY maxCountry æFp Packages.p æC maxCountry = verThailand; æKY mdy æFp Packages.p æC mdy = 0; æKY minCountry æFp Packages.p æC minCountry = verUS; æKY minLeadingZ æFp Packages.p æC minLeadingZ = 64; æKY mntLdingZ æFp Packages.p æC mntLdingZ = 64; æKY myd æFp Packages.p æC myd = 3; æKY NumToString æFp Packages.p æT PROCEDURE æTN $A9EE æD PROCEDURE NumToString(theNum: LONGINT;VAR theString: Str255); æDT NumToString(theNum,theString); æMM æRI NumToString procedure I-489 æC _____________________________________________________________________________________ Trap macro _NumToString On entry A0: pointer to theString (length byte followed by characters) D0: theNum (long integer) On exit A0: pointer to theString _____________________________________________________________________________________ NumToString converts theNum to a string that represents its decimal value, and returns the result in theString. If the value is negative, the string begins with a minus sign; otherwise, the sign is omitted. Leading zeroes are suppressed, except that the value 0 produces '0'. For example: theNum theString 12 '12' -23 '-23' 0 '0' æMM æRI NumToString procedure I-489 æKY putCancel æFp Packages.p æC putCancel = 2; æKY putDlgID æFp Packages.p æC putDlgID = -3999; æKY putDrive æFp Packages.p æC putDrive = 6; æKY putEject æFp Packages.p æC putEject = 5; æKY putName æFp Packages.p æC putName = 7; æKY putSave æFp Packages.p æC putSave = 1; æKY secLeadingZ æFp Packages.p æC secLeadingZ = 32; æKY SFGetFile æFp Packages.p æT PROCEDURE æTN $A9EA æD PROCEDURE SFGetFile(where: Point;prompt: Str255;fileFilter: ProcPtr; numTypes: INTEGER;typeList: SFTypeList;dlgHook: ProcPtr;VAR reply: SFReply); æDT SFGetFile(where,prompt,fileFilter,numTypes,typeList,dlgHook,reply); æRT 47, 77, 80, 107, 205 æRI SFGetFile procedure I-523, N47, N77-1, N80-1, N99, P-125, 162, 181 æC SFGetFile displays a dialog box listing the names of a specific group of files from which the user can select one to be opened (as during an Open command). It then repeatedly gets and handles events until the user either confirms the command after choosing a file name or aborts the command by clicking Cancel in the dialog. It reports the user's reply by filling the fields of the reply record specified by the reply parameter, as described above under "Using the Standard File Package". The general appearance of the standard SFGetFile dialog box is shown in Figure S-5. File names are sorted in order of the ASCII codes of their characters, ignoring diacritical marks and mapping lowercase characters to their uppercase equivalents. If there are more file names than can be displayed at one time, the scroll bar is active; otherwise, the scroll bar is inactive. The where parameter specifies the location of the top left corner of the dialog box in global coordinates. The prompt parameter is ignored; it's there for historical purposes only. The fileFilter, numTypes, and typeList parameters determine which files appear in the dialog box. SFGetFile first looks at numTypes and typeList to determine what types of files to display, then it executes the function pointed to by fileFilter (if any) to do additional filtering on which files to display. File types are discussed in the manual THE STRUCTURE OF A MACINTOSH APPLICATION. For example, if the application is concerned only with pictures, you won't want to display the names of any text files. Pass -1 for numTypes to display all types of files; otherwise, pass the number of file types you want to display, and pass the types themselves in typeList. The SFTypeList data type is defined as follows: TYPE SFTypeList = ARRAY [0..3] OF OSTYPE; Note: This array is declared for a reasonable maximum number of types (four). If you need to specify more than four types, declare your own array type with the desired number of entries (and use the @ operator to pass a pointer to it). If fileFilter isn't NIL, SFGetFile executes the function it points to for each file, to determine whether the file should be displayed. The fileFilter function has one parameter and returns a Boolean value. For example: FUNCTION MyFileFilter (paramBlock: ParmBlkPtr) : BOOLEAN; SFGetFile passes this function the file information it gets by calling the File Manager procedure PBGetFInfo. The function selects which files should appear in the dialog by returning FALSE for every file that should be shown and TRUE for every file that shouldn't be shown. Note: As described in the File Manager manual, a flag can be set that tells the Finder not to display a particular file's icon on the desktop; this has no effect on whether SFGetFile will list the file name. If you want to use the standard SFGetFile dialog box, pass NIL for dlgHook; otherwise, see the information for advanced programmers below. Like SFPutFile, SFGetFile repeatedly calls the Dialog Manager procedure ModalDialog. When an event involving an enabled dialog item occurs, ModalDialog handles the event and returns the item number, and SFGetFile responds as follows: • If the Eject or Drive button is clicked, or a disk is inserted, SFGetFile responds as described above under "About the Standard File Package". • If clicking or dragging occurs in the scroll bar, the contents of the dialog box are redrawn accordingly. • If a file name is clicked, it's selected and stored in the fName field of the reply record. (SFGetFile keeps track of whether a file name is currently selected, and makes the Open button inactive if not.) • If the Open button is clicked, SFGetFile returns control to the application with the first field of the reply record set to TRUE. • If a file name is double-clicked, SFGetFile responds as if the user clicked the file name and then the Open button. • If the Cancel button in the dialog is clicked, SFGetFile returns control to the application with the first field of the reply record set to FALSE. If a key (other than a modifier key) is pressed, SFGetFile selects the first file name starting with the character typed. If no file name starts with that character, it selects the first file name starting with a character whose ASCII code is greater than the character typed. Advanced programmers: You can create your own dialog box rather than use the standard SFGetFile dialog. To do this, you must provide your own dialog template and store it in your application's resource file with the same resource ID that the standard template has in the system resource file: CONST getDlgID = -4000; {SFGetFile dialog template ID} Note: The SFPGetFile procedure, described below, lets you use any resource ID for your nonstandard dialog box. Your dialog template must specify that the dialog window be invisible, and your dialog must contain all the standard items, as listed below. The appearance and location of these items in your dialog may be different. You can make an item "invisible" by giving it a display rectangle that's off the screen. The display rectangle for each in the standard dialog box is given below. The rectangle for the standard dialog box itself is (0,0,348,136). Item Number Item Standard display rectangle 1 Open button (152,28,232,46) 2 Invisible button (1152,59,1232,77) 3 Cancel button (152,90,232,108) 4 UserItem for disk name (248,28,344,46) 5 Eject button (256,59,336,77) 6 Drive button (256,90,336,108) 7 UserItem for file name list (12,11,125,125) 8 UserItem for scroll bar (124,11,140,125) 9 UserItem for gray line (244,20,245,116) 10 Invisible text (statText) (1044,20,1145,116) If your dialog has additional items beyond the standard ones, or if you want to handle any of the standard items in a nonstandard manner, you must write your own dlgHook function and point to it with dlgHook. Your dlgHook function should have two parameters and return an integer value. For example, this is how it would be declared if it were named MyDlg: FUNCTION MyDlg (item: INTEGER; theDialog: DialogPtr) : INTEGER; Immediately after calling ModalDialog, SFGetFile calls you dlgHook function, passing it the item number returned by ModalDialog and a pointer to the dialog record describing you dialog box. Using these two parameters, your dlgHook function should determine how to handle the event. There are predefined constants for the item numbers of standard enabled items, as follows: CONST getOpen = 1; {Open button} getCancel = 3; {Cancel button} getEject = 5; {Eject button} getDrive = 6; {Drive button} getNmList = 7; {userItem for file name list} getScroll = 8; {userItem for scroll bar} ModalDialog also returns "fake" item numbers in the following situations, which are detected by its filterProc function: • When a disk-inserted event occurs, it returns 100. • When a key-down event occurs, it returns 1000 plus the ASCII code of the character. After handling the event (or, perhaps, after ignoring it) your dlgHook function must return an item number to SFGetFile. If the item number is one of those listed above, SFGetFile responds in the standard way; otherwise, it does nothing. æKY SFPGetFile æFp Packages.p æT PROCEDURE æTN $A9EA æD PROCEDURE SFPGetFile(where: Point;prompt: Str255;fileFilter: ProcPtr; numTypes: INTEGER;typeList: SFTypeList;dlgHook: ProcPtr;VAR reply: SFReply; dlgID: INTEGER;filterProc: ProcPtr); æDT SFPGetFile(where,prompt,fileFilter,numTypes,typeList,dlgHook,reply,dlgID, filterProc); æRT 47, 80 æRI SFPGetFile procedure I-526 æC SFPGetFile is an alternative to SFGetFile for advanced programmers who want to use a nonstandard dialog box. It's the same as SFGetFile except for the two additional parameters dlgID and filterProc. DlgID is the resource ID of the dialog template to be used instead of the standard one (so you can use whatever ID you wish rather than the same one as the standard). The filterProc parameter determines how ModalDialog will filter events when called by SFPGetFile. If filterProc is NIL, ModalDialog does the standard filtering that it does when called by SFGetFile; otherwise, filterProc should point to a function for ModalDialog to execute after doing the standard filtering. Note, however, that the standard filtering will detect key-down events only if the dialog template ID is the standard one. æRT 47 æRI SFPPutFile procedure I-523 æKY SFPutFile æFp Packages.p æT PROCEDURE æD PROCEDURE SFPutFile(where: Point;prompt: Str255;origName: Str255;dlgHook: ProcPtr; VAR reply: SFReply); æDT SFPutFile(where,prompt,origName,dlgHook,reply); æMM æRT 47, 80, 107, 226 æRI SFPutFile procedure I-519, P-125, 128, 162, 181 æC SFPutFile displays a dialog box allowing the user to specify a file to which data will be written (as during a Save or Save As command). It then repeatedly gets and handles events until the user either confirms the command after entering an appropriate file name or aborts the command by clicking Cancel in the dialog. It reports the user's reply by filling the fields of the reply record specified by the reply parameter, as described above; the fType field of this record isn't used. The general appearance of the standard SFPutFile dialog box is shown in Figure S-2. The where parameter specifies the location of the top left corner of the dialog box in global coordinates. The prompt parameter is a line of text to be displayed as a statText item in the dialog box, where shown in Figure S-2. The origName parameter contains text that appears as an enabled, selected editText item; for the standard document-saving commands, it should be the current name of the document, or the empty string (to display an insertion point) if the document hasn't been named yet. If you want to use the standard SFPutFile dialog box, pass NIL for dlgHook; otherwise, see the information for advanced programmers below. SFPutFile repeatedly calls the Dialog Manager procedure ModalDialog. When an event involving an enabled dialog item occurs, ModalDialog handles the event and returns the item number, and SFPutFile responds as follows: • If the Eject or Drive button is clicked, or a disk is inserted, SFPutFile responds as described above under "About the Standard File Package". • Text entered into the editText item is stored in the fName field of the reply record. (SFPutFile keeps track of whether there's currently any text in the item, and makes the Save button inactive if not.) • If the Save button is clicked, SFPutFile determines whether the file name in the fName field of the reply record is appropriate. If so, it returns control to the application with the first field of the reply record set to TRUE; otherwise, it responds accordingly, as described below. • If the Cancel button in the dialog is clicked, SFPutFile returns control to the application with the first field of the reply record set to FALSE. Note: Notice that disk insertion is one of the user actions listed above, even though ModalDialog normally ignores disk-inserted events. The reason this works is that SFPutFile calls ModalDialog with a filterProc function that checks for a disk-inserted event and returns a "fake", very large item number if one occurs; SFPutFile recognizes this item number as an indication that a disk was inserted. The situations that may cause an entered name to be inappropriate, and SFPutFile's response to each, are as follows: • If a file with the specified name already exists on the disk and is different from what was passed in the origName parameter, the alert in Figure S-3 is displayed. If the user clicks Yes, the file name is appropriate. • If the disk to which the file should be written is locked, the alert in Figure S-4 is displayed. If a system error occurs, a similar alert is displayed, with a corresponding message explaining the problem. Note: The user may specify a disk name (preceding the file name and separated from it by a colon). If the disk isn't currently in a drive, an alert similar to the one in Figure S-4 is displayed. The ability to specify a disk name is supported for historical reasons only; users should not be encouraged to do it. After the user clicks No or Cancel in response to one of these alerts, SFPutFile dismisses the alert box and continues handling events (so a different name may be entered). Advanced programmers: You can create your own dialog box rather than use the standard SFPutFile dialog. To do this, you must provide your own dialog template and store it in your application's resource file with the same resource ID that the standard template has in the system resource file: CONST putDlgID = -3999; {SFPutFile dialog template ID} Note: The SFPPutFile procedure, described below lets you use any resource ID for your nonstandard dialog box. Your dialog template must specify that the dialog window be invisible, and your dialog must contain all the standard items, as listed below. The appearance and location of these items in your dialog may be different. You can make an item "invisible" by giving it a display rectangle that's off the screen. The display rectangle for each item in the standard dialog box is given below. The rectangle for the standard dialog box itself is (0,0,304,104). Item Number Item Standard display rectangle 1 Save button (12,74,82,92) 2 Cancel button (114,74,184,92) 3 Prompt string (statText) (12,12,184,28) 4 UserItem for disk name (209,16,295,34) 5 Eject button (217,43,287,61) 6 Drive button (217,74,287,92) 7 EditText item for file name (14,34,182,50) 8 UserItem for gray line (200,16,201,88) Note: Remember that the display rectangle for any "invisible" item must be at least about 20 pixels wide. If your dialog has additional items beyond the standard ones, or if you want to handle any of the standard items in a nonstandard manner, you must write your own dlgHook function and point to it with dlgHook. Your dlgHook function should have two parameters and return an integer value. For example, this is how it would be declared if it were named MyDlg: FUNCTION MyDlg (item: INTEGER; theDialog: DialogPtr) : INTEGER; Immediately after calling ModalDialog, SFPutFile calls your dlgHook function, passing it the item number returned by ModalDialog and a pointer to the dialog record describing your dialog box. Using these two parameters, your dlgHook function should determine how to handle the event. There are predefined constants for the item numbers of standard enabled items, as follows: CONST putSave = 1; {Saver button} putCancel = 2; {Cancel button} putEject = 5; {Eject button} putDrive = 6; {Drive button} putName = 7; {editText item for file name} ModalDialog also returns the "fake" item number 100 when a disk- inserted event occurs, as detected by its filterProc function. After handling the event (or, perhaps, after ignoring it) the dlgHook function must return an item number to SFPutFile. If the item number is one of those listed above, SFPutFile responds in the standard way; otherwise, it does nothing. Note: For advanced programmers who want to change the appearance of the alerts displayed when an inappropriate file name is entered, the resource IDs of those alerts in the system resource file are listed below. Alert Resource ID Existing file -3996 Locked disk -3997 System error -3995 Disk not found -3994 æMM æRT 47, 80, 107, 226 æRI SFPutFile procedure I-519, P-125, 128, 162, 181 æKY SFReply æFp Packages.p æT RECORD æC SFReply = RECORD good: BOOLEAN; copy: BOOLEAN; fType: OSType; vRefNum: INTEGER; version: INTEGER; fName: Str63; END; æKY SFTypeList æFp Packages.p æT TYPE æC SFTypeList = ARRAY [0..3] OF OSType; æKY StringToNum æFp Packages.p æT PROCEDURE æTN $A9EE æD PROCEDURE StringToNum(theString: Str255;VAR theNum: LONGINT); æDT StringToNum(theString,theNum); æMM æRI StringToNum procedure I-490 æC _____________________________________________________________________________________ Trap macro _StringToNum On entry A0: pointer to theString (length byte followed by characters) On exit DO: theNum (long integer) _____________________________________________________________________________________ Given a string representing a decimal integer, StringToNum converts it to the corresponding integer and returns the result in theNum. The string may begin with a plus or minus sign. For example: theString theNum '12' 12 '-23' -23 '-0' 0 '055' 55 The magnitude of the integer is converted modulo 2^32, and the 32-bit result is negated if the string begins with a minus sign; integer overflow occurs if the magnitude is greater than 2^31-1. (Negation is done by taking the two's complement--reversing the state of each bit and then adding 1.) For example: theString theNum '2147483648' (magnitude is 2^31) -2147483648 '-2147483648' -2147483648 '4294967295' (magnitude is 2^31) -1 '-4294967295' 1 StringToNum doesn't actually check whether the characters in the string are between '0' and '9'; instead, since the ASCII codes for '0' through '9' are $30 through $39, it just masks off the last four bits and uses them as a digit. For example, '2:' is converted to the number 30 because the ASCI code for ':' is $3A. Leading spaces before the first digit are treated as zeroes, since the ASCII code for a space is $20. Given that the ASCII codes for 'C', 'A', and 'T' are $43, $41, and $54, respectively, consider the following examples: theString theNum 'CAT' 314 '+CAT' 314 '-CAT' -314 æMM æRI StringToNum procedure I-490 æKY supDay æFp Packages.p æC supDay = 1; {suppress day of month} æKY supMonth æFp Packages.p æC supMonth = 4; {suppress month} æKY supWeek æFp Packages.p æC supWeek = 2; {suppress day of week} æKY supYear æFp Packages.p æC supYear = 8; {suppress year} æKY verArabia æFp Packages.p æC verArabia = 16; æKY verAustralia æFp Packages.p æC verAustralia = 15; æKY verBelgiumLux æFp Packages.p æC verBelgiumLux = 6; æKY verBritain æFp Packages.p æC verBritain = 2; æKY verChina æFp Packages.p æC verChina = 52; æKY verCyprus æFp Packages.p æC verCyprus = 23; æKY verDenmark æFp Packages.p æC verDenmark = 9; æKY verFinland æFp Packages.p æC verFinland = 17; æKY verFrance æFp Packages.p æC verFrance = 1; æKY verFrCanada æFp Packages.p æC verFrCanada = 11; æKY verFrSwiss æFp Packages.p æC verFrSwiss = 18; æKY verGermany æFp Packages.p æC verGermany = 3; æKY verGreece æFp Packages.p æC verGreece = 20; æKY verGrSwiss æFp Packages.p æC verGrSwiss = 19; æKY verIceland æFp Packages.p æC verIceland = 21; æKY verIreland æFp Packages.p æC verIreland = 50; æKY verIsrael æFp Packages.p æC verIsrael = 13; æKY verItaly æFp Packages.p æC verItaly = 4; æKY verJapan æFp Packages.p æC verJapan = 14; æKY verKorea æFp Packages.p æC verKorea = 51; æKY verMalta æFp Packages.p æC verMalta = 22; æKY verNetherlands æFp Packages.p æC verNetherlands = 5; æKY verNorway æFp Packages.p æC verNorway = 12; æKY verPortugal æFp Packages.p æC verPortugal = 10; æKY verSpain æFp Packages.p æC verSpain = 8; æKY verSweden æFp Packages.p æC verSweden = 7; æKY verTaiwan æFp Packages.p æC verTaiwan = 53; æKY verThailand æFp Packages.p æC verThailand = 54; æKY verTurkey æFp Packages.p æC verTurkey = 24; æKY verUS æFp Packages.p æC verUS = 0; æKY verYugoslavia æFp Packages.p æC verYugoslavia = 25; æKY ydm æFp Packages.p æC ydm = 5; æKY ymd æFp Packages.p æC ymd = 2; æKY zeroCycle æFp Packages.p æC zeroCycle = 1; {0:00 AM/PM format} æKY Palettes.p æKL ActivatePalette AnimateEntry AnimatePalette CopyPalette CTab2Palette DisposePalette GetEntryColor GetEntryUsage GetNewPalette GetPalette InitPalettes NewPalette NSetPalette Palette2CTab PmBackColor PmForeColor SetEntryColor SetEntryUsage SetPalette ColorInfo Palette PaletteHandle PalettePtr pmAllUpdates pmAnimated PmBackColor PmBackColor pmBkUpdates pmCourteous pmDithered pmExplicit pmFgUpdates PmForeColor PmForeColor pmNoUpdates pmTolerant SetEntryColor æKY Palette,PalettePtr,PaletteHandle æFp Palettes.p æT TYPE æC PalettePtr = ^Palette; PaletteHandle = ^PalettePtr; Palette = RECORD pmEntries: INTEGER; {entries in pmTable} pmDataFields: ARRAY [0..6] OF INTEGER; {private fields} pmInfo: ARRAY [0..0] OF ColorInfo; END; TYPE PaletteHandle = ^PalettePtr; PalettePtr = ^Palette; Palette = RECORD pmEntries: integer; {entries in pmInfo} pmDataFields: array [0..6] of integer; {private fields} pmInfo: array [0..0] of ColorInfo; END; Field descriptions pmEntries The pmEntries field contains the number of entries in the pmTable. pmDataFields The pmDataFields field contains an array of integers that are used internally by the Palette Manager. pmInfo The pmInfo field contains an array of ColorInfo records. æKY ActivatePalette æFp Palettes.p æT PROCEDURE æTN $AA94 æD PROCEDURE ActivatePalette(srcWindow: WindowPtr); æDT ActivatePalette(srcWindow); æMM æRI ActivatePalette procedure V-162 æC ActivatePalette is the routine called by the Window Manager when your window’s status changes: for example, when it opens, closes, moves, or becomes frontmost. You should call ActivatePalette after making changes to a palette with the utility routines described below. Such changes do not take effect until the next call to ActivatePalette, thereby allowing you to make a series of palette changes without any immediate change in the color environment. If srcWindow is frontmost, ActivatePalette examines the information stored in the palette associated with srcWindow and attempts to provide the color environment described therein. It determines a list of devices on which to render the palette by intersecting the port rect of the srcWindow with each device. If the intersection is not empty, and if the device has a Color Look-Up Table (CLUT), then ActivatePalette checks to see if the color environment is sufficient. If a change is required, ActivatePalette calls the Color Manager to reserve or modify the device’s color entries as required. It then generates update events for all affected windows which desire color updates. æKY AnimateEntry æFp Palettes.p æT PROCEDURE æTN $AA99 æD PROCEDURE AnimateEntry(dstWindow: WindowPtr;dstEntry: INTEGER;srcRGB: RGBColor); æDT AnimateEntry(dstWindow,dstEntry,srcRGB); æRI AnimateEntry procedure V-164 æC AnimateEntry changes the RGB value of dstEntry in the palette associated with dstWindow to the color specified by srcRGB. Each device for which an index has been reserved is immediately modified to contain the new value. This is not considered to be a change to the device’s color environment since no other windows should be using the animated entry. If the palette entry is not an animating color, or if the associated indexes are no longer reserved, no animation is performed. If you have blocked color updates in a window, by using SetPalette with CUpdates set to FALSE, you may observe undesired animation. This will occur when ActivatePalette reserves device indexes for animation which are already used in the window. Redrawing the window, which normally occurs as the result of a color update event, will remove any animating colors which do not belong to it. æKY AnimatePalette æFp Palettes.p æT PROCEDURE æTN $AA9A æD PROCEDURE AnimatePalette(dstWindow: WindowPtr;srcCTab: CTabHandle;srcIndex: INTEGER; dstEntry: INTEGER;dstLength: INTEGER); æDT AnimatePalette(dstWindow,srcCTab,srcIndex,dstEntry,dstLength); æRI AnimatePalette procedure V-164 æC AnimatePalette performs a function similar to AnimateEntry, but it acts upon a range of palette entries. Beginning at srcIndex (which has a minimum value of 0), the next dstLength entries are copied from srcCTab to dstWindow’s palette, beginning at dstEntry. If srcCTab is not sufficiently large to accommodate the request, as many entries are modified as possible and the remaining entries are left unchanged. æKY ColorInfo æFp Palettes.p æT RECORD æC ColorInfo = RECORD ciRGB: RGBColor; {true RGB values} ciUsage: INTEGER; {color usage} ciTolerance: INTEGER; {tolerance value} ciDataFields: ARRAY [0..2] OF INTEGER; {private fields} END; »COLOR PALETTE RECORDS _______________________________________________________________________________ The basic data structure for a color palette is the ColorInfo record. It consists of the following: TYPE ColorInfo = RECORD ciRGB: RGBColor; {absolute RGB values} ciUsage: INTEGER {color usage information} ciTolerance: INTEGER; {tolerance value} ciFlags: INTEGER; {private field} ciPrivate: LONGINT; {private field} END; Field descriptions ciRGB The ciRGB is the absolute RGB value defined by Color QuickDraw. ciUsage The ciUsage field contains color usage information that determines the properties of a color. ciTolerance The ciTolerance is a value used to determine if a color is close enough to the color chosen; if the tolerance value is exceeded, the preferred color is rendered in the device’s color table for the selected index. ciFlags The ciFlags field is used internally by the Palette Manager. ciPrivate The ciPrivate field is used internally to store information about color allocation: not for use by application. The data structure for a color palette is made up of an array of ColorInfo records, plus other information relating to the use of the colors within the palette. The 'pltt' resource is an image of the Palette data structure. Note: The palette is accessed through the Palette Manager routines only: do not attempt to directly access any of the fields in this data structure. æKY CopyPalette æFp Palettes.p æT PROCEDURE æTN $AAA1 æD PROCEDURE CopyPalette(srcPalette: PaletteHandle;dstPalette: PaletteHandle; srcEntry: INTEGER;dstEntry: INTEGER;dstLength: INTEGER); æDT CopyPalette(srcPalette,dstPalette,srcEntry,dstEntry,dstLength); æMM æRT 211 æKY CTab2Palette æFp Palettes.p æT PROCEDURE æTN $AA9F æD PROCEDURE CTab2Palette(srcCTab: CTabHandle;dstPalette: PaletteHandle; srcUsage: INTEGER;srcTolerance: INTEGER); æDT CTab2Palette(srcCTab,dstPalette,srcUsage,srcTolerance); æMM æRI CTab2Palette procedure V-165 æC CTab2Palette is a convenience procedure which copies the fields from an existing ColorTable record into an existing Palette record. If the records are not the same size then the Palette record is resized to match the number of entries in the ColorTable record. If dstPalette has any entries allocated for animation on any display device, these entries are relinquished prior to copying the new colors. If you wish to effect color table animation you can change the colors in a palette, and on corresponding devices, with the AnimateEntry and AnimatePalette routines described above. Changes made to a palette by CTab2Palette don’t take effect until the next ActivatePalette is performed. If either the color table handle or the palette handle are NIL, no operation is performed. æKY DisposePalette æFp Palettes.p æT PROCEDURE æTN $AA93 æD PROCEDURE DisposePalette(srcPalette: PaletteHandle); æDT DisposePalette(srcPalette); æMM æRI DisposePalette procedure V-162 æC DisposePalette disposes of a Palette object. If the palette has any entries allocated for animation on any display device, these entries are relinquished prior to deallocation of the object. æKY GetEntryColor æFp Palettes.p æT PROCEDURE æTN $AA9B æD PROCEDURE GetEntryColor(srcPalette: PaletteHandle;srcEntry: INTEGER; VAR dstRGB: RGBColor); æDT GetEntryColor(srcPalette,srcEntry,dstRGB); æRI GetEntryColor procedure V-164 æC GetEntryColor allows your application to access the color of a palette entry. The color may be modified by using the SetEntryColor routine described below. æKY GetEntryUsage æFp Palettes.p æT PROCEDURE æTN $AA9D æD PROCEDURE GetEntryUsage(srcPalette: PaletteHandle;srcEntry: INTEGER; VAR dstUsage: INTEGER;VAR dstTolerance: INTEGER); æDT GetEntryUsage(srcPalette,srcEntry,dstUsage,dstTolerance); æRI GetEntryUsage procedure V-165 æC GetEntryUsage allows your application to access the usage fields of a palette entry, namely ciUsage and ciTolerance. These fields may be modified by using the SetEntryUsage routine described below. æKY GetNewPalette æFp Palettes.p æT FUNCTION æTN $AA92 æD FUNCTION GetNewPalette(PaletteID: INTEGER): PaletteHandle; æDT myVariable := GetNewPalette(PaletteID); æMM æRI GetNewPalette function V-162 æC GetNewPalette fetches a Palette object from the Resource Manager and initializes it. If you open a new color window with GetNewCWindow, this routine is called automatically with paletteID equal to the window’s resource ID. A palette resource is identified by type 'pltt'. A paletteID of 0 is reserved for the system palette resource which is used as the default palette for noncolor windows and color windows without assigned palettes. æKY GetPalette æFp Palettes.p æT FUNCTION æTN $AA96 æD FUNCTION GetPalette(srcWindow: WindowPtr): PaletteHandle; æDT myVariable := GetPalette(srcWindow); æRT 211 æRI GetPalette function V-163 æC GetPalette returns a handle to the palette associated with srcWindow. If no palette is associated with srcWindow, or if srcWindow is not a color window, GetPalette returns NIL. æKY InitPalettes æFp Palettes.p æT PROCEDURE æTN $AA90 æD PROCEDURE InitPalettes; æDT InitPalettes; æMM æRT 211 æRI InitPalettes procedure V-161 æC InitPalettes initializes the Palette Manager. It searches for devices which support a Color Look-Up Table (CLUT) and initializes an internal data structure for each one. This call is made by InitWindows and should not have to be made by your application. æKY NewPalette æFp Palettes.p æT FUNCTION æTN $AA91 æD FUNCTION NewPalette(entries: INTEGER;srcColors: CTabHandle;srcUsage: INTEGER; srcTolerance: INTEGER): PaletteHandle; æDT myVariable := NewPalette(entries,srcColors,srcUsage,srcTolerance); æMM æRI NewPalette function V-161 æC NewPalette allocates a new Palette object which contains a table of colors with enough room for “entries” colors. It fills the table with as many RGB values from srcColors as it has or as it can fit. It sets the usage field of each color to srcUsage and the tolerance value of each color to srcTolerance. If no color table is provided (srcColors = NIL) then all colors in the palette are set to black (red = $0000, green = $0000, blue = $0000 ). æKY NSetPalette æFp Palettes.p æT PROCEDURE æTN $AA95 æD PROCEDURE NSetPalette(dstWindow: WindowPtr;srcPalette: PaletteHandle; nCUpdates: INTEGER); æDT NSetPalette(dstWindow,srcPalette,nCUpdates); æRT 211 æKY Palette2CTab æFp Palettes.p æT PROCEDURE æTN $AAA0 æD PROCEDURE Palette2CTab(srcPalette: PaletteHandle;dstCTab: CTabHandle); æDT Palette2CTab(srcPalette,dstCTab); æMM æRI Palette2CTab procedure V-166 æC Palette2CTab is a convenience procedure which copies all of the colors from an existing Palette record into an existing ColorTable record. If the records are not the same size then the ColorTable record is resized to match the number of entries in the Palette record. If either the palette handle or the color table handle are NIL, no operation is performed. æKY pmAllUpdates æFp Palettes.p æC pmAllUpdates = $E000; {all updates} æKY PmBackColor æFp Palettes.p æT PROCEDURE æTN $AA98 æD PROCEDURE PmBackColor(dstEntry: INTEGER); æDT PmBackColor(dstEntry); æMM æRT 211 æRI PmBackColor procedure V-163 æC These routines enable applications to specify foreground and background drawing colors with the assistance of the Palette Manager. Substitute these for Color Quickdraw’s RGBForeColor and RGBBackColor routines when you wish to use a color from a palette. You may still use RGBForeColor and RGBBackColor in the normal way whenever you wish to specify drawing colors, for example when you wish to use a color which is not contained in your palette. PmBackColor sets the RGB and index backcolor fields of the current cGrafPort according to the palette entry of the current cGrafPort (window) corresponding to dstEntry. For courteous and tolerant entries, this call performs an RGBBackColor using the RGB color of the palette entry. For animating colors it will select the recorded device index previously reserved for animation (if still present) and install it in the cGrafPort. The RGB backcolor field is set to the value from the palette entry. For explicit colors PmBackColor places (dstEntry modulo (MaxIndex+1)) into the cGrafPort, where MaxIndex is the largest index available in a device’s color table. When multiple devices are present with different depths, MaxIndex varies appropriately for each device. æKY pmBkUpdates æFp Palettes.p æC pmBkUpdates = $A000; {background updates only} æKY pmCourteous,pmDithered,pmTolerant,pmAnimated,pmExplicit æFp Palettes.p æC »Color Usage The Palette Manager uses one of four methods for selecting colors: • Courteous colors have no special properties. For such colors, the Palette Manager relies upon Color QuickDraw to select appropriate pixel values. Colors with specified usages that can’t be satisfied by the Palette Manager will default to courteous colors. This occurs, for example, when drawing to a device with no color look-up table, such as a direct or fixed device. Courteous colors don’t change the color environment in any way. • Tolerant colors cause a change in the color environment unless the fit to the best matching available color falls within a separately specified tolerance value. • Animating colors are reserved by a palette and are unavailable to (and can’t be matched by) any other request for color. • Explicit colors always generate the corresponding entry in the device’s color table. These color types are specified when using Palette Manager routines by using the following constants: CONST { Usage constants } pmCourteous = $0000; pmDithered = $0001; {reserved for future use} pmTolerant = $0002; pmAnimated = $0004; pmExplicit = $0008; When you specify colors for a palette within a 'pltt' resource, you will usually assign the same usage value to each color in the palette. However, if for some reason a particular color must be used differently than the other colors in the palette, it can be assigned a different usage value, either within the resource file, or within the application through use of the SetEntryUsage routine. The sections that follow provide more information on these color types. »Courteous Colors Courteous colors are provided for two reasons. First, they are a convenient placeholder. If your application uses only a small number of colors you can place each of them in a palette, ordered according to your preference. Suppose you have a palette resource which consists of a set of eight colors, namely white, black, red, orange, yellow, green, blue, and violet, in that order, each with a usage specified as courteous. Assuming further that the palette resource ID number matched that of a color window (myColorWindow) you opened earlier, the following calls will paint a rectangle (myRect) in yellow (palette entry 4, where white is 0): SetPort (myColorWindow); PmForeColor (4); PaintRect (myRect); This is exactly analogous to the following sequence of calls made using Color Quickdraw routines, where yellowRGB is of type ColorSpec: with yellowRGB do begin {done once during your initialization} red := $FFFF; green := $FFFF; blue := $0000 end; SetPort (myColorWindow); RGBForeColor (yellowRGB); PaintRect (myRect); The second reason for providing courteous colors is not immediately apparent. It involves how colors are selected for palettes which use animation. The Palette Manager has access to all palettes used by all windows throughout the system. When deciding which of a device’s colors to allocate for animation, it checks each window currently drawn on that device to see which colors the windows are using. It then chooses the color which is least used and reserves that for animation. In the first example shown above, the Palette Manager would try to avoid the eight colors used in your palette, even though they are just courteous colors. In the second example it would have no knowledge of your colors and might steal them unnecessarily, and when your window is redrawn the selected colors might not be as close to the desired colors as they previously were. If you intend to use only a limited number of colors it is therefore best to place them in the window’s palette so the Palette Manager will know about them. »Tolerant Colors Tolerant colors allow you to change the current color environment according to your needs. When your window becomes the frontmost window on a device its palette and the colors contained therein are given preference. Each tolerant color is compared to the best unique match available in the current color environment (for each device on which the window is drawn). When the difference between your color and the best available match is greater than the tolerance you have specified the Palette Manager will modify the color environment to provide an exact match to your color. The tolerance value associated with each palette entry is compared to a measure of the difference between two RGBColor values. This difference is an approximation of the distance between the two points as measured in a Cartesian coordinate system where the axes are the unsigned red, green, and blue values. The distance formula used is shown below: Δ RGB = maximum of (abs(Red1–Red2), abs(Green1–Green2), abs(Blue1–Blue2)) A value of $5000 is generally sufficient to allow matching without updates in reasonably well-balanced color environments. A tolerance value of $0000 means that only an exact match is acceptable. Any value of $0xxx, other than $0000, is reserved, and should not be used in applications. If your palette requires more colors than are currently available the Palette Manager will check to see if any other palette has reserved entries for animation. If so it will dereserve them and make them available for your palette. If you ask for more than are available on a device, the Palette Manager cannot honor your request. However, you can still call PmForeColor for such colors; as mentioned earlier, such colors default to courteous colors. Color QuickDraw will still select the best color available, which of course must match one of the colors elsewhere in your palette since the Palette Manager will only run out of colors after it has given your palette all that it has. Two exceptions to this rule are noted below. See the “Black, White, and Palette Customization” section and the “Palette Prioritization” section describing the interaction among colors of different usages in a single palette. »Animating Colors Animating colors allow you to reserve device indexes for color table animation. Each animating color is checked to see if it already has a reserved index for the target device. If it does not, the Palette Manager attempts to find a suitable index. This is done by checking all windows to see what colors they use, and which device indexes match those colors. The least frequently used indexes are then reserved for your palette. The reservation process is analogous to the Color Manager call ReserveEntry. The device index and its corresponding color value is removed from the matching scheme used by Color Quickdraw; you cannot draw with it by calling RGBForeColor. However, when you call PmForeColor the Palette Manager will locate the reserved index and configure your window’s port to draw with it. On multiple devices this will likely be a different index for each device, but this process will be invisible to your application. After reserving one or more device indexes for each animating entry it detects, the Palette Manager will change the color environment to match the RGB values specified in the palette. To use an animating color you must first draw with it using PmForeColor or PmBackColor. To effect color table animation you can use either AnimateEntry (for a single color) or AnimatePalette (for a contiguous set of colors). These calls are described in the section titled “Palette Manager Routines”. »Explicit Colors Explicit colors are provided as a convenience for users who wish to use colors in very special ways. The RGB value in a palette is completely ignored if a color is an explicit color. Explicit colors cause no change in the color environment and are not counted for purposes of animation. Explicit colors always match the corresponding device index. A PmForeColor call with a parameter of 12 will place a value of (12 modulo (MaxIndex+1)) into the foreground color field of your window’s cGrafPort, where MaxIndex is the maximum available index for each device under consideration. When you draw with an explicit color, you get whatever color the device index currently contains. One interesting use for explicit colors is that it allows you to monitor the color environment on a device. For example, you could draw a grid of 256 explicit colors, 16-by-16, in a small window. The colors shown are exactly those in the device’s color table. If color table animation is taking place simultaneously the corresponding colors in the small window will animate as well. If you display such a window on a 4-bit device, the first 16 colors will match the 16 colors available in the device and each row thereafter will be a copy of the first row. However, the main purpose for explicit colors is to provide a convenient indexed color interface. Using the Color Manager, you can establish a known color environment using the SetEntries routine on each device of interest. You can then easily select any of these colors for drawing by setting your window’s palette to contain as many explicit colors as are in the target device with the greatest number of indexes. PmForeColor will configure the cGrafPort to draw with the index of your choice. Warning: You should not use explicit colors in this fashion if you intend your application to coexist in multi-application environments such as those provided by MultiFinder™ or A/UX™ or when using color desk accessories that depend upon the Palette Manager. However, for certain types of applications, especially those which are written for a known device environment, explicit colors will tend to make indexed color manipulation much more convenient. æKY pmFgUpdates æFp Palettes.p æC pmFgUpdates = $C000; {foreground updates only} æKY PmForeColor æFp Palettes.p æT PROCEDURE æTN $AA97 æD PROCEDURE PmForeColor(dstEntry: INTEGER); æDT PmForeColor(dstEntry); æMM æRT 211 æRI PmForeColor procedure V-163 æC These routines enable applications to specify foreground and background drawing colors with the assistance of the Palette Manager. Substitute these for Color Quickdraw’s RGBForeColor and RGBBackColor routines when you wish to use a color from a palette. You may still use RGBForeColor and RGBBackColor in the normal way whenever you wish to specify drawing colors, for example when you wish to use a color which is not contained in your palette. PmForeColor sets the RGB and index forecolor fields of the current cGrafPort according to the palette entry of the current cGrafPort (window) corresponding to dstEntry. For courteous and tolerant entries, this call performs an RGBForeColor using the RGB color of the palette entry. For animating colors it will select the recorded device index previously reserved for animation (if still present) and install it in the cGrafPort. The RGB forecolor field is set to the value from the palette entry. For explicit colors PmForeColor places (dstEntry modulo (MaxIndex+1)) into the cGrafPort, where MaxIndex is the largest index available in a device’s CLUT. When multiple devices are present with different depths, MaxIndex varies appropriately for each device. æKY pmNoUpdates æFp Palettes.p æC pmNoUpdates = $8000; {no updates} æKY SetEntryColor æFp Palettes.p æT PROCEDURE æTN $AA9C æD PROCEDURE SetEntryColor(dstPalette: PaletteHandle;dstEntry: INTEGER; srcRGB: RGBColor); æDT SetEntryColor(dstPalette,dstEntry,srcRGB); æRI SetEntryColor procedure V-165 æC SetEntryColor provides a convenient way for your application to modify the color of a single palette entry. When you perform a SetPaletteEntry, the entry is marked as having changed, but no change occurs in the color environment. The change will be effected upon the next call to ActivatePalette. Modified entries are marked such that the palette will be updated even though no update might be required by a change in the color environment. æKY SetEntryUsage æFp Palettes.p æT PROCEDURE æTN $AA9E æD PROCEDURE SetEntryUsage(dstPalette: PaletteHandle;dstEntry: INTEGER; srcUsage: INTEGER;srcTolerance: INTEGER); æDT SetEntryUsage(dstPalette,dstEntry,srcUsage,srcTolerance); æRI SetEntryUsage procedure V-165 æC SetEntryUsage provides a convenient way for your application to modify the color of a single palette entry. When you perform a SetEntryUsage, the entry is marked as having changed, but no change occurs in the color environment. The change will be effected upon the next call to ActivatePalette. Modified entries are marked such that the palette will be updated even though no update might be required by a change in the color environment. If either myUsage or myTolerance are set to $FFFF (–1) they will not be changed. This call is provided to allow easy modifications to a palette created with NewPalette or modified by CTab2Palette. In such cases the ciUsage and ciTolerance fields are homogeneous since only one value can be designated for each. You will typically call SetEntryUsage after those calls in order to adjust and customize your palette. æKY SetPalette æFp Palettes.p æT PROCEDURE æTN $AA95 æD PROCEDURE SetPalette(dstWindow: WindowPtr;srcPalette: PaletteHandle; cUpdates: BOOLEAN); æDT SetPalette(dstWindow,srcPalette,cUpdates); æRT 211 æRI SetPalette procedure V-162 æC SetPalette changes the palette associated with dstWindow to srcPalette. It also records whether the window wants to receive updates as a result of a change to its color environment. If you want dstWindow to be updated whenever its color environment changes, set cUpdates to TRUE. æKY Perf.p æKL InitPerf PerfControl PerfDump TermPerf AInts ALongs HInts PInts PLongs TP2PerfGlobals TPerfGlobals æKY HInts,PInts,AInts æFp Perf.p æT TYPE æC PInts = ^AInts; HInts = ^PInts; AInts = ARRAY [1..8000] OF INTEGER; { PerfGlobals are declared as a record, so main program can allocate as globals, desk accessory can add to globals allocated via pointer, print driver can allocate via low memory, etc. } æKY PLongs,ALongs æFp Perf.p æT TYPE æC PLongs = ^ALongs; ALongs = ARRAY [1..8000] OF LONGINT; æKY TP2PerfGlobals,TPerfGlobals æFp Perf.p æT TYPE æC TP2PerfGlobals = ^TPerfGlobals; TPerfGlobals = RECORD startROM: LONGINT; {ROM Base} romHits: LONGINT; {used if MeasureROM is false} misses: LONGINT; {count of PC values outside measured memory} segArray: PLongs; {array of segment handles} sizeArray: PLongs; {array of segment sizes} idArray: HInts; {array of segment rsrc IDs} baseArray: PLongs; {array of offsets to counters for each segment} samples: PLongs; {samples buffer} buffSize: LONGINT; {size of samples buffer in bytes} timeInterval: INTEGER; {number of clock intervals between interrupts} bucketSize: INTEGER; {size of buckets power of 2} log2buckSize: INTEGER; {used in CvtPC} pcOffset: INTEGER; {offset to the user PC at interrupt time.} numMeasure: INTEGER; {# Code segments (w/o jump table)- ROM etc.} firstCode: INTEGER; {index of first Code segment} takingSamples: BOOLEAN; {true if sampling is enabled} measureROM: BOOLEAN; measureCode: BOOLEAN; ramSeg: INTEGER; {index of "segment" record to cover RAM > 0 if RAM (misses) are to be bucketed.} ramBase: LONGINT; {beginning of RAM being measured.} measureRAMbucketSize: INTEGER; measureRAMlog2buckSize: INTEGER; romVersion: INTEGER; vRefNum: INTEGER; {Volume where the report file is to be created} volumeSelected: BOOLEAN; {True if user selects the report file name} rptFileName: Str255; {Report file name} rptFileCreator: Str255; {Report File Creator} rptFileType: Str255; {Report File type} getResType: ResType; {Resource type} END; æKY InitPerf æFp Perf.p æT FUNCTION æD FUNCTION InitPerf(VAR thePerfGlobals: TP2PerfGlobals;timerCount: INTEGER; codeAndROMBucketSize: INTEGER;doROM: BOOLEAN;doAppCode: BOOLEAN;appCodeType: Str255; romID: INTEGER;romName: Str255;doRAM: BOOLEAN;ramLow: LONGINT;ramHigh: LONGINT; ramBucketSize: INTEGER): BOOLEAN; æDT myVariable := InitPerf(thePerfGlobals,timerCount,codeAndROMBucketSize, doROM,doAppCode,appCodeType,romID,romName,doRAM,ramLow,ramHigh,ramBucketSize); æC called once to setup Performance monitoring æKY PerfControl æFp Perf.p æT FUNCTION æD FUNCTION PerfControl(thePerfGlobals: TP2PerfGlobals;turnOn: BOOLEAN): BOOLEAN; æDT myVariable := PerfControl(thePerfGlobals,turnOn); æC Call this to turn off/on measuring. Returns previous state. æKY PerfDump æFp Perf.p æT FUNCTION æD FUNCTION PerfDump(thePerfGlobals: TP2PerfGlobals;reportFile: Str255; doHistogram: BOOLEAN;rptFileColumns: INTEGER): INTEGER; æDT myVariable := PerfDump(thePerfGlobals,reportFile,doHistogram,rptFileColumns); æC Call this to dump the statistics into a file. æKY TermPerf æFp Perf.p æT PROCEDURE æD PROCEDURE TermPerf(thePerfGlobals: TP2PerfGlobals); æDT TermPerf(thePerfGlobals); æC if InitPerf succeeds then TermPerf must be called before terminating program. æKY Picker.p æKL CMY2RGB Fix2SmallFract GetColor HSL2RGB HSV2RGB RGB2CMY RGB2HSL RGB2HSV SmallFract2Fix CMYColor HSLColor HSVColor MaxSmallFract SmallFract æKY CMY2RGB æFp Picker.p æT PROCEDURE æTN $A82E æD PROCEDURE CMY2RGB(cColor: CMYColor;VAR rColor: RGBColor); æDT CMY2RGB(cColor,rColor); æMM æC The Color Picker provides six procedures for converting color values between CMY and RGB, and between HSL or HSV and RGB. Most developers will not need to use these routines. PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); PROCEDURE HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor); PROCEDURE RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor); For developmental simplicity in switching between the HLS and HSV models, HLS is reordered into HSL. Thus both models start with hue and saturation values; value/lightness/brightness is last. The CMY, HSL, and HSV structures are defined by ColorPicker with SmallFract values rather than INTEGER values (as in RGBColor). A SmallFract value is the fractional part of a Fixed number, which is the low-order word. The INTEGER values in RGBColor are actually used as unsigned integer-sized values; by using SmallFracts, ColorPicker avoids sign extension problems in the conversion math. æKY CMYColor æFp Picker.p æT RECORD æC CMYColor = RECORD cyan: SmallFract; magenta: SmallFract; yellow: SmallFract; END; æKY Fix2SmallFract æFp Picker.p æT FUNCTION æTN $A82E æD FUNCTION Fix2SmallFract(f: Fixed): SmallFract; æDT myVariable := Fix2SmallFract(f); æMM æRI Fix2SmallFract function V-175 æC The Color Picker provides two functions for converting between SmallFract and Fixed numbers. Most developers will not need to use these facilities. FUNCTION Fix2SmallFract(f: Fixed): SmallFract; FUNCTION SmallFract2Fix(s: SmallFract): Fixed; A SmallFract can represent a value between 0 and 65,535. They can be assigned directly to and from INTEGERs. æKY GetColor æFp Picker.p æT FUNCTION æTN $A82E æD FUNCTION GetColor(where: Point;prompt: Str255;inColor: RGBColor;VAR outColor: RGBColor): BOOLEAN; æDT myVariable := GetColor(where,prompt,inColor,outColor); æMM æRI GetColor function V-174 æC GetColor displays the Color Picker dialog box on the screen, with its top-left corner located at where. (The where Point should be on the main gDevice.) If where = (0,0), the dialog box is positioned neatly on the screen, centered horizontally, and with one third of the empty space above the box, two thirds below, whatever the screen size. The prompt string is displayed in the upper-left corner of the dialog box. InColor is the starting color, which the user may want for comparison, and is displayed immediately below the current output color (the one the user is picking). OutColor is set to the last color value the user picked, if and only if the user clicks OK. On entry, it is treated as undefined, so the output color sample originally matches the input. While the color being picked may vary widely, the input color sample remains fixed, and clicking in the input sample resets the output color sample to match it. GetColor returns TRUE if the user exits via the OK button, or FALSE if the user cancels. Assembly-language note: the trap macro for the Color Picker Package is _Pack12. The routine selectors are as follows: Fix2SmallFract .EQU 1 SmallFract2Fix .EQU 2 CMY2RGB .EQU 3 RGB2CMY .EQU 4 HSL2RGB .EQU 5 RGB2HSL .EQU 6 HSV2RGB .EQU 7 RGB2HSV .EQU 8 GetColor .EQU 9 æKY HSL2RGB æFp Picker.p æT PROCEDURE æTN $A82E æD PROCEDURE HSL2RGB(hColor: HSLColor;VAR rColor: RGBColor); æDT HSL2RGB(hColor,rColor); æMM æRI HSL2RGB procedure V-175 æC The Color Picker provides six procedures for converting color values between CMY and RGB, and between HSL or HSV and RGB. Most developers will not need to use these routines. PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); PROCEDURE HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor); PROCEDURE RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor); For developmental simplicity in switching between the HLS and HSV models, HLS is reordered into HSL. Thus both models start with hue and saturation values; value/lightness/brightness is last. The CMY, HSL, and HSV structures are defined by ColorPicker with SmallFract values rather than INTEGER values (as in RGBColor). A SmallFract value is the fractional part of a Fixed number, which is the low-order word. The INTEGER values in RGBColor are actually used as unsigned integer-sized values; by using SmallFracts, ColorPicker avoids sign extension problems in the conversion math. æKY HSLColor æFp Picker.p æT RECORD æC HSLColor = RECORD hue: SmallFract; {Fraction of circle, red at 0} saturation: SmallFract; {0-1, 0 for gray, 1 for pure color} lightness: SmallFract; {0-1, 0 for black, 1 for white} END; æKY HSV2RGB æFp Picker.p æT PROCEDURE æTN $A82E æD PROCEDURE HSV2RGB(hColor: HSVColor;VAR rColor: RGBColor); æDT HSV2RGB(hColor,rColor); æMM æRI HSV2RGB procedure V-175 æC The Color Picker provides six procedures for converting color values between CMY and RGB, and between HSL or HSV and RGB. Most developers will not need to use these routines. PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); PROCEDURE HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor); PROCEDURE RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor); For developmental simplicity in switching between the HLS and HSV models, HLS is reordered into HSL. Thus both models start with hue and saturation values; value/lightness/brightness is last. The CMY, HSL, and HSV structures are defined by ColorPicker with SmallFract values rather than INTEGER values (as in RGBColor). A SmallFract value is the fractional part of a Fixed number, which is the low-order word. The INTEGER values in RGBColor are actually used as unsigned integer-sized values; by using SmallFracts, ColorPicker avoids sign extension problems in the conversion math. æKY HSVColor æFp Picker.p æT RECORD æC HSVColor = RECORD hue: SmallFract; {Fraction of circle, red at 0} saturation: SmallFract; {0-1, 0 for gray, 1 for pure color} value: SmallFract; {0-1, 0 for black, 1 for max intensity} END; æKY MaxSmallFract æFp Picker.p æC MaxSmallFract = $0000FFFF; {Maximum small fract value, as long} æKY RGB2CMY æFp Picker.p æT PROCEDURE æTN $A82E æD PROCEDURE RGB2CMY(rColor: RGBColor;VAR cColor: CMYColor); æDT RGB2CMY(rColor,cColor); æMM æRI RGB2CMY procedure V-175 æC The Color Picker provides six procedures for converting color values between CMY and RGB, and between HSL or HSV and RGB. Most developers will not need to use these routines. PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); PROCEDURE HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor); PROCEDURE RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor); For developmental simplicity in switching between the HLS and HSV models, HLS is reordered into HSL. Thus both models start with hue and saturation values; value/lightness/brightness is last. The CMY, HSL, and HSV structures are defined by ColorPicker with SmallFract values rather than INTEGER values (as in RGBColor). A SmallFract value is the fractional part of a Fixed number, which is the low-order word. The INTEGER values in RGBColor are actually used as unsigned integer-sized values; by using SmallFracts, ColorPicker avoids sign extension problems in the conversion math. æKY RGB2HSL æFp Picker.p æT PROCEDURE æTN $A82E æD PROCEDURE RGB2HSL(rColor: RGBColor;VAR hColor: HSLColor); æDT RGB2HSL(rColor,hColor); æMM æRI RGB2HSL procedure V-175 æC The Color Picker provides six procedures for converting color values between CMY and RGB, and between HSL or HSV and RGB. Most developers will not need to use these routines. PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); PROCEDURE HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor); PROCEDURE RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor); For developmental simplicity in switching between the HLS and HSV models, HLS is reordered into HSL. Thus both models start with hue and saturation values; value/lightness/brightness is last. The CMY, HSL, and HSV structures are defined by ColorPicker with SmallFract values rather than INTEGER values (as in RGBColor). A SmallFract value is the fractional part of a Fixed number, which is the low-order word. The INTEGER values in RGBColor are actually used as unsigned integer-sized values; by using SmallFracts, ColorPicker avoids sign extension problems in the conversion math. æKY RGB2HSV æFp Picker.p æT PROCEDURE æTN $A82E æD PROCEDURE RGB2HSV(rColor: RGBColor;VAR hColor: HSVColor); æDT RGB2HSV(rColor,hColor); æMM æRI RGB2HSV procedure V-175 æC The Color Picker provides six procedures for converting color values between CMY and RGB, and between HSL or HSV and RGB. Most developers will not need to use these routines. PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); PROCEDURE HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor); PROCEDURE RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor); For developmental simplicity in switching between the HLS and HSV models, HLS is reordered into HSL. Thus both models start with hue and saturation values; value/lightness/brightness is last. The CMY, HSL, and HSV structures are defined by ColorPicker with SmallFract values rather than INTEGER values (as in RGBColor). A SmallFract value is the fractional part of a Fixed number, which is the low-order word. The INTEGER values in RGBColor are actually used as unsigned integer-sized values; by using SmallFracts, ColorPicker avoids sign extension problems in the conversion math. æKY SmallFract æFp Picker.p æT TYPE æC SmallFract = INTEGER; æKY SmallFract2Fix æFp Picker.p æT FUNCTION æTN $A82E æD FUNCTION SmallFract2Fix(s: SmallFract): Fixed; æDT myVariable := SmallFract2Fix(s); æMM æRI SmallFract2Fix function V-175 æC The Color Picker provides two functions for converting between SmallFract and Fixed numbers. Most developers will not need to use these facilities. FUNCTION Fix2SmallFract(f: Fixed): SmallFract; FUNCTION SmallFract2Fix(s: SmallFract): Fixed; A SmallFract can represent a value between 0 and 65,535. They can be assigned directly to and from INTEGERs. æKY Printing.p æKL PrClose PrCloseDoc PrClosePage PrCtlCall PrDlgMain PrDrvrClose PrDrvrDCE PrDrvrOpen PrDrvrVers PrError PrGeneral PrintDefault PrJobDialog PrJobInit PrJobMerge PrNoPurge PrOpen PrOpenDoc PrOpenPage PrPicFile PrPurge PrSetError PrStlDialog PrStlInit PrValidate bDraftLoop bSpoolLoop bUser1Loop bUser2Loop draftBitsOp feedCut feedFanfold feedMechCut feedOther fHiResOK fNewRunBit fWeOpenedRF getRotnOp getRslDataOp iFMgrCtl iIOAbort iMemFullErr iMscCtl invalColReq iPFMaxPgs iPrAbort iPrBitsCtl iPrDevCtl iPrDrvrRef iPrEvtCtl iPrIOCtl iPrPgFract iPrPgFst iPrPgMax iPrRelease iPrSavPFil iPvtCtl lHiPaintBits lHiScreenBits lPaintBits lPrDocClose lPrDocOpen lPrEvtAll lPrEvtTop lPrLFSixth lPrLFStd lPrLineFeed lPrPageClose lPrPageEnd lPrPageOpen lPrReset lScreenBits noDraftBitsOp NoSuchRsl pPrGlobals Rect RgType1 scanBT scanLR scanRL scanTB setRslOp TDftBitsBlk TFeed TGetRotnBlk TGetRslBlk TGnlData THLong THPfPgDir THPrint THWord TLong TPfPgDir TPLong TPPfPgDir TPPrDlg TPPrInfo TPPrint TPPrJob TPPrPort TPPrStatus TPPrStl TPPrXInfo TPrDlg TPRect TPrInfo TPrint TPrJob TPrPort TPrStatus TPrStl TPrXInfo TPWord TRslRec TRslRg TScan TSetRslBlk TWord æKY THLong,TPLong,TLong æFp Printing.p æT TYPE æC TPLong = ^TLong; THLong = ^TPLong; TLong = RECORD CASE INTEGER OF 0: (w1,w0: TWord); 1: (b1,b0: LONGINT); 2: (p0: Ptr); 3: (h0: Handle); 4: (pt: Point); END; æKY THPfPgDir,TPPfPgDir,TPfPgDir æFp Printing.p æT TYPE æC TPPfPgDir = ^TPfPgDir; THPfPgDir = ^TPPfPgDir; TPfPgDir = RECORD iPages: INTEGER; iPgPos: ARRAY [0..128] OF LONGINT; {ARRAY [0..iPfMaxPgs] OF LONGINT} END; æKY TPrint,TPPrint,THPrint æFp Printing.p æT TYPE æC TPPrint = ^TPrint; THPrint = ^TPPrint; TPrint = RECORD iPrVersion: INTEGER; {(2) Printing software version} prInfo: TPrInfo; {(14) the PrInfo data associated with the current style.} rPaper: Rect; {(8) The paper rectangle [offset from rPage]} prStl: TPrStl; {(8) This print request's style.} prInfoPT: TPrInfo; {(14) Print Time Imaging metrics} prXInfo: TPrXInfo; {(16) Print-time (expanded) Print info record.} prJob: TPrJob; {(20) The Print Job request (82) Total of the above; 120-82 = 38 bytes needed to fill 120} printX: ARRAY [1..19] OF INTEGER; {Spare to fill to 120 bytes!} END; Print records are referred to by handles. Their structure is as follows: TYPE THPrint = ^TPPrint; TPPrint = ^TPrint; TPrint = RECORD iPrVersion: INTEGER; {Printing Manager version} prInfo: TPrInfo; {printer information subrecord} rPaper: Rect; {paper rectangle} prStl: TPrStl; {additional device information} prInfoPT: TPrInfo; {used internally} prXInfo: TPrXInfo; {additional device information} prJob: TPrJob; {job subrecord} printX: ARRAY[1..19] OF INTEGER {not used} END; Warning: Your application should not change the data in the print record—be sure to use the standard dialogs for setting this information. The only fields you’ll need to set directly are some containing optional information in the job subrecord (explained below). Attempting to set other values directly in the print record can produce unexpected results. IPrVersion identifies the version of the Printing Manager that initialized this print record. If you try to use a print record that’s invalid for the current version of the Printing Manager or for the currently installed printer, the Printing Manager will correct the record by filling it with default values. The other fields of the print record are discussed in separate sections below. Note: Whenever you save a document, you should write an appropriate print record in the document’s resource file. This lets the document “remember” its own printing parameters for use the next time it’s printed. æKY THWord,TPWord,TWord æFp Printing.p æT TYPE æC TPWord = ^TWord; THWord = ^TPWord; TWord = PACKED RECORD CASE INTEGER OF 0: (c1,c0: CHAR); 1: (b1,b0: SignedByte); 2: (usb1,usb0: Byte); 3: (n3,n2,n1,n0: TN); 4: (f15,f14,f13,f12,f11,f10,f9,f8,f7,f6,f5,f4,f3,f2,f1,f0: BOOLEAN); 5: (i0: INTEGER); END; æKY TPPrDlg,TPrDlg æFp Printing.p æT TYPE æC TPPrDlg = ^TPrDlg; TPrDlg = RECORD Dlg: DialogRecord; {The Dialog window} pFltrProc: ProcPtr; {The Filter Proc.} pItemProc: ProcPtr; {The Item evaluating proc.} hPrintUsr: THPrint; {The user's print record.} fDoIt: BOOLEAN; fDone: BOOLEAN; lUser1: LONGINT; {Four longs for user's to hang global data.} lUser2: LONGINT; {...Plus more stuff needed by the particular printing dialog.} lUser3: LONGINT; lUser4: LONGINT; END; æKY TPrInfo,TPPrInfo æFp Printing.p æT TYPE æC TPPrInfo = ^TPrInfo; TPrInfo = RECORD iDev: INTEGER; {Font mgr/QuickDraw device code} iVRes: INTEGER; {Resolution of device, in device coordinates} iHRes: INTEGER; {..note: V before H => compatable with Point.} rPage: Rect; {The page (printable) rectangle in device coordinates.} END; »The Printer Information Subrecord The printer information subrecord (field prInfo of the print record) gives you the information needed for page composition. It’s defined as follows: TYPE TPrInfo = RECORD iDev: INTEGER; {used internally} iVRes: INTEGER; {vertical resolution of printer} iHRes: INTEGER; {horizontal resolution of printer} rPage: Rect {page rectangle} END; RPage is the page rectangle, representing the boundaries of the printable page: The printing grafPort’s boundary rectangle, portRect, and clipRgn are set to this rectangle. Its top left corner always has coordinates (0,0); the coordinates of the bottom right corner give the maximum page height and width attainable on the given printer, in dots. Typically these are slightly less than the physical dimensions of the paper, because of the printer’s mechanical limitations. RPage is set as a result of the style dialog. The rPage rectangle is inside the paper rectangle, specified by the rPaper field of the print record. RPaper gives the physical paper size, defined in the same coordinate system as rPage (see Figure 4). Thus the top left coordinates of the paper rectangle are typically negative and its bottom right coordinates are greater than those of the page rectangle. IVRes and iHRes give the printer’s vertical and horizontal resolution in dots per inch. Thus, if you divide the width of rPage by iHRes, you get the width of the page rectangle in inches. æKY TPrJob,TPPrJob æFp Printing.p æT TYPE æC TPPrJob = ^TPrJob; TPrJob = RECORD iFstPage: INTEGER; {Page Range.} iLstPage: INTEGER; iCopies: INTEGER; {No. copies.} bJDocLoop: SignedByte; {The Doc style: Draft, Spool, .., and ..} fFromUsr: BOOLEAN; {Printing from an User's App (not PrApp) flag} pIdleProc: ProcPtr; {The Proc called while waiting on IO etc.} pFileName: StringPtr; {Spool File Name: NIL for default.} iFileVol: INTEGER; {Spool File vol, set to 0 initially} bFileVers: SignedByte; {Spool File version, set to 0 initially} bJobX: SignedByte; {An eXtra byte.} END; »The Job Subrecord The job subrecord (field prJob of the print record) contains information about a particular printing job. Its contents are set as a result of the job dialog. •••Refer to Figure 4.••• Figure 4–Page and Paper Rectangles The job subrecord is defined as follows: TYPE TPrJob = RECORD iFstPage: INTEGER; {first page to print} iLstPage: INTEGER; {last page to print} iCopies: INTEGER; {number of copies} bJDocLoop: SignedByte; {printing method} fFromUsr: BOOLEAN; {used internally} pIdleProc: ProcPtr; {background procedure} pFileName: StringPtr; {spool file name} iFileVol: INTEGER; {spool file volume reference number} bFileVers: SignedByte; {spool file version number} bJobX: SignedByte {used internally} END; BJDocLoop designates the printing method that the Printing Manager will use. It will be one of the following predefined constants: CONST bDraftLoop = 0; {draft printing} bSpoolLoop = 1; {spool printing} Draft printing means that the document will be printed immediately. Spool printing means that printing may be deferred: The Printing Manager writes out a representation of the document’s printed image to a disk file (or possibly to memory); this information is then converted into a bit image and printed. For details about the printing methods, see the “Methods of Printing” section below. The Printing Manager sets the bJDocLoop field; your application should not change it. IFstPage and iLstPage designate the first and last pages to be printed. These page numbers are relative to the first page counted by the Printing Manager. The Printing Manager knows nothing about any page numbering placed by an application within a document. ICopies is the number of copies to print. The Printing Manager automatically handles multiple copies for spool printing or for printing on the LaserWriter. Your application only needs this number for draft printing on the Imagewriter. PIdleProc is a pointer to the background procedure (explained below) for this printing operation. In a newly initialized print record this field is set to NIL, designating the default background procedure, which just polls the keyboard and cancels further printing if the user types Command-period. You can install a background procedure of your own by storing a pointer to your procedure directly into the pIdleProc field. For spool printing, your application may optionally provide a spool file name, volume reference number, and version number (described in the File Manager chapter): • PFileName is the name of the spool file. This field is initialized to NIL, and generally not changed by the application. NIL denotes the default file name (normally 'Print File') stored in the printer resource file. • IFileVol is the volume reference number of the spool file. This field is initialized to 0, representing the default volume. You can use the File Manager function SetVol to change the default volume, or you can override the default setting by storing directly into this field. • BFileVers is the version number of the spool file, initialized to 0. æKY TPPrPort,TPrPort æFp Printing.p æT TYPE æC TPPrPort = ^TPrPort; TPrPort = RECORD gPort: GrafPort; {The Printer's graf port.} gProcs: QDProcs; {..and its procs} lGParam1: LONGINT; {16 bytes for private parameter storage.} lGParam2: LONGINT; lGParam3: LONGINT; lGParam4: LONGINT; fOurPtr: BOOLEAN; {Whether the PrPort allocation was done by us.} fOurBits: BOOLEAN; {Whether the BitMap allocation was done by us.} END; æKY TPrStatus,TPPrStatus æFp Printing.p æT TYPE æC TPPrStatus = ^TPrStatus; TPrStatus = RECORD iTotPages: INTEGER; {Total pages in Print File.} iCurPage: INTEGER; {Current page number} iTotCopies: INTEGER; {Total copies requested} iCurCopy: INTEGER; {Current copy number} iTotBands: INTEGER; {Total bands per page.} iCurBand: INTEGER; {Current band number} fPgDirty: BOOLEAN; {True if current page has been written to.} fImaging: BOOLEAN; {Set while in band's DrawPic call.} hPrint: THPrint; {Handle to the active Printer record} pPrPort: TPPrPort; {Ptr to the active PrPort} hPic: PicHandle; {Handle to the active Picture} END; The prStatus parameter is a printer status record that PrPicFile will use to report on its progress: TYPE TPrStatus = RECORD iTotPages: INTEGER; {number of pages in spool file} iCurPage: INTEGER; {page being printed} iTotCopies: INTEGER; {number of copies requested} iCurCopy: INTEGER; {copy being printed} iTotBands: INTEGER; {used internally}